This integrations service supports the following events from a GitLab repository into specific Mattermost channels by formatting output from GitLab's outgoing webhooks to Mattermost's incoming webhooks.
| Event | Enabled by default | Comments |
|---|---|---|
| push | ✗ | Can be enabled with the flag --push |
| tag | ✗ | Can be enabled with the flag --tag |
| issue | ✓ | Can be disabled with the flag --no-issue |
| comment | ✓ | Can be disabled with the flag --no-comment |
| merge request | ✓ | Can be disabled with the flag --no-merge-request |
| build | ✓ | Can be disabled with the flag --no-ci |
Not currently supported: wiki page events.
This service is currently tested against the events sent by Gitlab 8.14.x.
To run this integration you need:
- A server running some sort of Linux and Python (tested with versions 2.7, 3.3, 3.4, 3.5).
- A GitLab account with a repository to which you have administrator access
- A Mattermost account where incoming webhooks are enabled
Many web server options will work, below we provide instructions for Heroku and a general Linux/Ubuntu server.
The following procedure shows how to install this project on a Linux web server running Ubuntu 14.04. The following instructions work behind a firewall so long as the web server has access to your GitLab and Mattermost instances.
To install this project using a Linux-based web server, you will need a Linux/Ubuntu 14.04 web server supporting Python >= 2.7. Other compatible operating systems and Python versions should also work.
Here's how to start:
-
Set up your Mattermost instance to receive incoming webhooks
-
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Integrations > Incoming Webhooks.
-
Click Add incoming webhook.
-
Specify the name of the webhook and select the channel in which you want GitLab notifications to appear.
-
Copy the contents next to URL of the new webhook you just created (we'll refer to this as
https://<your-mattermost-webhook-URL>). -
Set up this project to run on your web server
-
Set up a Linux Ubuntu 14.04 server either on your own machine or on a hosted service, like AWS.
-
SSH into the machine, or just open your terminal if you're installing locally.
-
Confirm Python >= 2.7 or a compatible version is installed by running:
python --versionIf it's not installed you can find it here
-
Install pip and other essentials:
sudo apt-get install python-pip python-dev build-essential
-
Create a virtualenv if you want to keep things separated:
[sudo] pip install virtualenv- to handle virtual envs even simpler consider the virtualenvwrapper:
[sudo] pip install virtualenvwrapper
-
Install integration requirements:
[sudo] pip install git+https://github.com/NotSqrt/mattermost-integration-gitlab
-
Run the server:
mattermost_gitlab --helpmattermost_gitlab $MATTERMOST_WEBHOOK_URLYou will see the output similar toRunning on http://0.0.0.0:5000/ (Press CTRL+C to quit). This is default IP:PORT pair the integration service will listen on. We will refer to this address as thehttp://<your-mattermost-integration-URL>). You may change the IP:PORT with the adequate command-line options (see --help)
-
You may want to add a script to auto-start mattermost_gitlab at boot:
# /etc/init/mattermost-gitlab.conf
start on runlevel [2345]
stop on runlevel [016]
respawn
# Change this to the relevant user
setuid mattermost
# Change the path if necessary, add options if need be
exec /home/mattermost/ve/bin/mattermost_gitlab http://mattermost/hooks/hook-idInstead of an upstart script you may want to handle the mattermost_gitlab with supervisor. The sample config file can be as simple as:
[program:mattermost-gitlab]
user=mattermost
command=/home/mattermost/ve/mattermost/bin/mattermost_gitlab http://mattermost/hooks/hook-id
autostart=true
autorestart=true
stdout_logfile=/home/mattermost/logs/mattermost_gitlab.log
redirect_stderr=trueAnother script using systemctl:
sudo touch /etc/systemd/system/mattermost_gitlab.servicesudo nano /etc/systemd/system/mattermost_gitlab.service- Copy the following lines into
/etc/systemd/system/mattermost_gitlab.service
[Unit]
Description=Mattermost gitlab integration
After=syslog.target network.target
[Service]
Type=simple
User=mattermost
Group=mattermost
ExecStart=/usr/local/bin/mattermost_gitlab http://mattermost/hooks/hook-id
PrivateTmp=yes
WorkingDirectory=/opt/mattermost #for omnibus installations, use /opt/gitlab/embedded/service/mattermost
Restart=always
RestartSec=30
LimitNOFILE=49152
[Install]
WantedBy=multi-user.targetsystemctl daemon-reloadsystemctl enable mattermost_gitlabsystemctl start mattermost_gitlab
Simply build docker image and run it. There are several environment variables that can be used to change behaviour of plugin (see entrypoint.sh)
docker build -t mattermost-integration-gitlab .
docker run -d -E MATTERMOST_WEBHOOK_URL=http://mattermost/hooks/hook-id mattermost-integration-gitlab-
Connect your project to your GitLab account for outgoing webhooks
-
Log in to your GitLab account and open the project from which you want to receive updates and to which you have administrator access. From the settings menu of the project, click on Webhooks. In the URL field enter
http://<your-mattermost-integration-URL>/new_event(notice extranew_eventURL argument). On this address the integration service will be receiving the events from your GitLab project. Make sure your URL has a leadinghttp://orhttps://. -
On the same page, under Trigger select the events you want to receive, Push events, Comment events, Issue events, Merge Request events for instance.
-
(Recommended but optional): Encrypt your connection from GitLab to your project by selecting Enable SSL verification. If this option is not available and you're not familiar with how to set it up, contact your GitLab System Administrator for help.
-
Click Add Webhook and check that your new webhook entry is added to the Webhooks section below the button.
-
Leave this page open as we'll come back to it to test that everything is working.
-
Test your webhook integration
-
If your GitLab project is in active development, return to the Settings > Web Hooks page of your GitLab project and click Test Hook to send a test message about one of your recent updates from your GitLab project to Mattermost. You should see a notification on the Gitlab page that the hook was successfully executed. In Mattermost, go to the channel which you specified when creating the URL for your incoming webhook and make sure that the message delivered successfully.
-
If your GitLab project is new, try creating a test issue and then verify that the issue is posted to Mattermost.
-
Remove the
export PUSH_TRIGGER=Trueline from your~/.bash_profileand source it againsource ~/.bash_profile. This was used for testing only, and is better left turned off for production -
If you have any issues, please go to https://github.com/NotSqrt/mattermost-integration-gitlab and let us know which steps in these instructions were unclear or didn't work.
❗ This was not adapted to the new python package.
To install this project using Heroku, you will need:
- A Heroku account, available for free at Heroku.com
- A GitHub account, available for free at GitHub.com
Here's how to start:
-
Create a copy of this project to manipulate
-
Log in to your GitHub account. Go to the Github repository of this project and click Fork in the top-right corner to create a copy of this project that you control and manipulate.
-
Deploy your project copy to Heroku
-
Go to your Heroku Dashboard and click + in the top-right corner then Create New App. Give your app a unqiue name (like
mattermost-gitlab-[YOUR_GITHUB_USERNAME]), select your region and click Create App. -
Heroku directs you to the Deploy tab of the dashboard for your new app, select GitHub as your connection option, then click Connect to GitHub at the bottom of the screen to authorize Herkou to access your GitHub account.
-
In the pop up window, click Authorize Application to allow Heroku to access your accounts repositories. On your Heroku dashboard, select your account in the first drop-down then search for the repo we created earlier by forking this project. Type
mattermost-integration-gitlabin the repo-name field, then click Search and then the Connect button once Heroku finds your repository. -
Scroll to the bottom of the new page. Under the Manual Deploy section, make sure the
masterbranch is selected then click Deploy Branch. After a few seconds you'll see a confirmation that the app has been deployed. -
At the top of your app dashboard, go to the Settings tab and scroll down to the Domains section. Copy the URL below Heroku Domain (we'll refer to this as
http://<your-heroku-domain>/and we'll need it in the next step) -
Leave your Heroku interface open as we'll come back to it to finish the setup.
-
Connect your project to your GitLab account for outgoing webhooks
-
Log in to GitLab account and open the project from which you want to receive updates and to which you have administrator access. From the left side of the project screen, click on Settings > Web Hooks. In the URL field enter
http://<your-heroku-domain>/from the previous step, plus the wordnew_eventto create an entry that readshttp://<your-heroku-domain>/new_eventso events from your GitLab project are sent to your Heroku server. Make sure your URL has a leadinghttp://orhttps://. -
On the same page, under Trigger select Push events, Comment events, Issue events, Merge Request events
-
(Recommended but optional): Encrypt your connection from GitLab to your project by selecting Enable SSL verification. If this option is not available and you're not familiar with how to set it up, contact your GitLab System Administrator for help.
-
Click Add Web Hook and check that your new webhook entry is added to the Web hooks section below the button.
-
Leave this page open as we'll come back to it to test that everything is working.
-
Set up your Mattermost instance to receive incoming webhooks
-
Log in to your Mattermost account. Click the three dot menu at the top of the left-hand side and go to Integrations > Incoming Webhooks.
-
Click Add incoming webhook.
-
Specify the name of the webhook and select the channel in which you want GitLab notifications to appear.
-
Copy the contents next to URL of the new webhook you just created (we'll refer to this as
https://<your-mattermost-webhook-URL>and add it to your Heroku server). -
Go back to your Heroku app dashboard under the Settings tab. Under the Config Variables section, click Reveal Config Vars
- Type
MATTERMOST_WEBHOOK_URLin the KEY field and pastehttps://<your-mattermost-webhook-URL>into the VALUE field, then click Add. - In the second KEY field, type
PUSH_TRIGGERand in the corresponding VALUE field, typeTrue.
- Type
-
Test your webhook integration
-
If your GitLab project is in active development, return to the Settings > Web Hooks page of your GitLab project and click Test Hook to send a test message about one of your recent updates from your GitLab project to Mattermost. You should see a notification on the Gitlab page that the hook was successfully executed. In Mattermost, go to the channel which you specified when creating the URL for your incoming webhook and make sure that the message delivered successfully.
-
If your GitLab project is new, try creating a test issue and then verify that the issue is posted to Mattermost.
-
Back on the settings tab of your Heroku app dashboard, under the Config Variables, click Reveal Config Vars and then click the
Xnext to the PUSH_TRIGGER field you added. This config variable was used for testing only, and is better left turned off for production -
If you have any issues, please go to http://forum.mattermost.org and let us know which steps in these instructions were unclear or didn't work.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent