GitLab to Mattermost Integration

This integration makes use of GitLab's outgoing webhooks and Mattermost's incoming webhooks to post GitLab events into Mattermost. You can find GitLab's outgoing webhooks described here and Mattermost's incoming webhooks described here.

Installing

This integration can be run from any web server that supports Python. The simplest way to get it up and running fast is to use Heroku.

Note: These installation instructions assume you have both a GitLab account with a project you have admin access to, and a Mattermost account where incoming webhooks are enabled.

Quick Install with Heroku

If you don't already have a Heroku account please go create one here (it's free!).

1. Deploy integration to Heroku

2. Fork the mattermost-integration-gitlab repository on GitHub by clicking Fork in the top-right and selecting your account if it asks.

3. Log in to Heroku and go to your dashboard.

4. Click the + in the top-right corner to add a new app.

5. Give your app a name and select your region, then click Create App.

6. On the Deploy screen, select GitHub at the top.

7. Use Connect to GitHub to authorize Herkou to access your GitHub account.

8. Select your account and type gitlab-mattermost into the repo-name field, then click Search.

9. Click the Connect button next to your repository.

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

11. Go to the Settings tab and under the Domains section copy the Heroku Domain.

12. Set up your GitLab outgoing webhook

13. Log in to your GitLab account, and go to the project you want events pushed from.

14. From your project page, click Settings in the bottom-left and then click Web Hooks. Note that you need have admin access to the project.

15. In the URL field, enter the following http://<your-heroku-domain>/new_event. Make sure to replace <your-heroku-domain> with the domain you copied in the last step of the previous install section.

16. Select all the Triggers you want to be posted into Mattermost, then click Add Web Hook.

17. Set up your Mattermost incoming webhook

18. Log in to your Mattermost account, and open your Account Settings by clicking in the top-left.

19. Go to the Integrations tab and click Edit next to Manage your incoming webhooks.

20. Select the channel you want the GitLab events to post to, then click Add.

21. Copy the URL from the newly created webhook.

22. Back on your Heroku app page, go to the Settings tab.

23. Under the Config Variables section, click the Reveal Config Vars button.

24. Enter MATTERMOST_WEBHOOK_URL for the KEY and paste the URL you copied as the VALUE, then click Add.

That's it! The integration should now be up and running on Heroku. It might take a minute for the Heroku process to finish starting but after that try performing an action on your GitLab project to trigger a post in Mattermost.

Manual Install

You of course don't have to use Heroku if you don't want to, you can easily set up the integration to run on practically any web server. It can even go behind your firewall as long as the integration still has access to your GitLab and Mattermost instances.

Below are the loose instructions for setting up the integration on a Linux/Ubuntu server.

3. Set up your Mattermost incoming webhook

4. Log in to your Mattermost account, and open your Account Settings by clicking in the top-left.

5. Go to the Integrations tab and click Edit next to Manage your incoming webhooks.

6. Select the channel you want the GitLab events to post to, then click Add.

7. Copy the URL from the newly created webhook and keep it handy for the next steps.

8. Set up your server

9. Stand-up a Linux/Ubuntu server on AWS, your own machine or somewhere else.

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

11. Make sure you have Python 2.7+ installed. If it's not installed you can find it here

    • python --version

12. Install pip and other essentials

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

13. Clone the repo with

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

14. Install integration requirements

    • sudo pip -r requirements.txt

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

    • export MATTERMOST_WEBHOOK_URL=<your-webhook-url> 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)

16. Source your bash profile

    • source ~/.bash_profile

17. Run the server

    • python server.py

18. Set up your GitLab outgoing webhook

19. Log in to your GitLab account, and go to the project you want events pushed from.

20. From your project page, click Settings in the bottom-left and then click Web Hooks.

21. In the URL field, enter the following <your-public-server-domain>/new_event. Make sure to replace <your-public-server-domain> with the domain that translates to your public server IP address. Don't forget to include the port if needed. For example, http://myserver.com:5000/new_event

22. Select all the Triggers you want to be posted into Mattermost, then click Add Web Hook.

That's it! The integration should now be running and ready to push GitLab events into Mattermost.