GitLab Integration Service for Mattermost

This integrations service posts issue, comment and merge request events from a GitLab repository into specific Mattermost channels by formatting output from GitLab's outgoing webhooks to Mattermost's incoming webhooks.

Mattermost community members are invited to fork this repo to create new integrations. To have your integration referenced on http://www.mattermost.org/webhooks/, please mail [email protected] or tweet to @MattermostHQ.

Requirements

To run this integration you need:

1. A web server supporting Python 2.7 or a compatible version to run this software (optionally, you could use a service provider like Heroku - see instructions below)
2. A GitLab account with a repository to which you have administrator access
3. A Mattermost account where incoming webhooks are enabled

Regarding 1. there are many options for web servers you can use, below we provide instructions for both Heroku and a general Linux/Ubuntu server to get something running:

Heroku-based Install

To install this project using Heroku, you will need:

1. A Heroku account, available for free from Heroku.com
2. A GitHub account, available for free from GitHub.com

Here's how to start:

1. Create a copy of this project to manipulate

2. From the Github repository of this project click Fork in the top-right corner to create a copy of this project that you control and can update as you like.

3. Deploy your project copy to Heroku

4. Go to your Heroku Dashboard and click + in the top-right corner then New App. Give your app a unqiue name (like mattermost-[YOUR_GITHUB_USERNAME]), select your region and click Create App.

5. On the Deploy screen, select GitHub at the top, then click Connect to GitHub to authorize Herkou to access your GitHub account.

6. Select your account and search for your repo name, for example mattermost-[YOUR_GITHUB_USERNAME], in the repo-name field, then click Search then the Connect button next to your repository.

7. Scroll to the bottom of the new page and under the Manual Deploy section click Deploy Branch, making sure the master branch is selected.

8. Go to Settings > Domains > Settings and 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)

9. Leave your Heroku interface open as we'll come back to it to finish the setup.

10. Connect your project to your GitLab account for outgoing webhooks

11. Log in to GitLab account and to 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 and in the URL field enter http://<your-heroku-domain>/ from the previous step, plus the word **new_event** to create an entry that reads http://<your-heroku-domain>/new_event so events from your GitLab project are sent to your Heroku server.

12. From the same page, under Trigger select Push events, Comment events, Issue events, Merge Request events

13. (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.

14. Click Add Web Hook to check that a new entry about your webhook is added to the Web hooks section below the button.

15. Leave this page open as we'll come back to it to test that everything is working.

16. Connect your project to your Mattermost account for incoming webhooks

17. Log in to your Mattermost account, and from three dot icon at the top of the left-hand menu go to Account Settings > Integrations > Incoming Webhooks > Edit.

18. Under Add a new incoming webhook select the channel in which you want GitLab notifications to appear, then click Add, which should create a new entry below.

19. From the new entry below, copy the contents next to URL (we'll refer to this as https://<your-mattermost-webhook-URL> and add it to your Heroku server).

20. Go to your Heroku app page and to Settings > Config Variables > Reveal Config Vars

    1. Add MATTERMOST_WEBHOOK_URL in the KEY field and paste https://<your-mattermost-webhook-URL> into VALUE and click Add
    2. In the second KEY field add PUSH_TRIGGER and in the corresponding VALUE field add True.

21. Test that everything is working

22. If your GitLab project is in active development, return to the webhooks 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

23. If your GitLab project is not active, if it's brand new for example, try creating an issue as a test, and check that the new issues is posted to Mattermost

24. Back on the settings page of your Heroku app, under the Config Variables, click Reveal Config Vars and then click the X next to the PUSH_TRIGGER field you added. This was used for testing only, and is better left turned off for production

25. If you have any issues, it's probably our fault for not well documenting the setup. So please go to http://forum.mattermost.org and let us know that our instructions didn't work, and let us know which steps were the most unclear.

Linux/Ubuntu 14.04 Web Server Install

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:

1. A Linux/Ubuntu 14.04 web server supporting Python 2.7 or a compatible version. Other compatible operating systems and Python versions should also work.

Here's how to start:

1. Set up your Mattermost instance to receive incoming webhooks

2. Log in to your Mattermost account, and from three dot icon at the top of the left-hand menu go to Account Settings > Integrations > Incoming Webhooks > Edit.

3. Under Add a new incoming webhook select the channel in which you want GitLab notifications to appear, then click Add, which should create a new entry below.

4. From the new entry below, copy the contents next to URL (we'll refer to this as https://<your-mattermost-webhook-URL> and add it to your Heroku server).

5. Set up this project to run on your web server

6. Set up a Linux Ubuntu 14.04 server either on your own machine or on a hosted service, like AWS.

7. SSH into the machine, or just open your terminal if you're installing locally.

8. Confirm Python 2.7 or a compatible version is installed by running:

   • python --version
   • If it's not installed you can find it here

9. Install pip and other essentials

   • sudo apt-get install python-pip python-dev build-essential

10. Clone this GitHub repo with

    • git clone https://github.com/mattermost/mattermost-integration-gitlab.git
    • cd mattermost-integration-gitlab

11. Install integration requirements

    • sudo pip -r requirements.txt

12. Add the following lines to your ~/.bash_profile

    • export MATTERMOST_WEBHOOK_URL=https://<your-mattermost-webhook-URL> This is the URL you copied in the last section
    • export PUSH_TRIGGER=True This is the URL you copied in the last section
    • export PORT=<your-port-number> The port number you want the integration to listen on (defaults to 5000)

13. Source your bash profile

    • source ~/.bash_profile

14. Run the server

    • python server.py

15. Connect your project to your GitLab account for outgoing webhooks

16. Log in to GitLab account and to 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 and in the URL field enter http://<your-web-server-domain>/ from the previous step, plus the word **new_event** to create an entry that reads http://<your-web-server-domain>/new_event so events from your GitLab project are sent to your web server.

17. From the same page, under Trigger select Push events, Comment events, Issue events, Merge Request events

18. (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.

19. Click Add Web Hook to check that a new entry about your webhook is added to the Web hooks section below the button.

20. Test that everything is working

21. If your GitLab project is in active development, return to the webhooks 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

22. If your GitLab project is not active, if it's brand new for example, try creating an issue as a test, and check that the new issues is posted to Mattermost

23. Remove the export PUSH_TRIGGER=True line from your ~/.bash_profile and source it again source ~/.bash_profile. This was used for testing only, and is better left turned off for production

24. If you have any issues, it's probably our fault for not well documenting the setup. So please go to http://forum.mattermost.org and let us know that our instructions didn't work, and let us know which steps were the most unclear.