Skip to content
GitHub integration for Mattermost
Python Dockerfile
Branch: master
Clone or download

Latest commit

ltratt Merge pull request #56 from ptersilie/wsgi
Update Readme with WSGI instructions
Latest commit 6b834f4 Feb 5, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
mattermostgithub Fix tests Sep 20, 2019
tests Added travis file Aug 7, 2018
.gitignore Update project structure (#35) May 24, 2017
.travis.yml We need py.test>=3.6 for pytest-flask Nov 7, 2018
LICENSE.txt Added license Jan 20, 2016 Add instructions on how to run with WSGI. Feb 5, 2020
requirements.txt Update requirements to latest version Feb 5, 2020 Fixed legacy method to run this which was broken by latest refactoring Oct 27, 2017 Update project structure (#35) May 24, 2017

Github integration for Mattermost

Inspired by mattermost-integration-gitlab this program creates a server using flask that listens for incoming GitHub event webhooks. These are then processed, formatted, and eventually forwarded to Mattermost where they are displayed inside a specified channel.


System requirements

  • Python3 or Python2

Application requirements

  • Flask (install with pip install flask)
  • requests (install with pip install requests)
  • (optional) PIL (install with pip install pillow) - needed to hide big Github avatars

All requirements can also be installed using the command

pip install -r requirements.txt

Installation and usage

  1. Clone the repository
  2. Within the mattermostgithub directory, copy config.template to and edit it with your details. For example:
USERNAME = "Github"
    'default' : ("", "off-topic"),
    'teamname/repositoryname' : ("", "repository-channel-id"),
    'teamname' : ("", "town-square"),
    'teamname/unimportantrepo' : None,
    "issues": ["labeled", "assigned"],
SECRET = 'secretkey'
    'hook': "/"
,   'address': ""
,   'port': 5000

Test the server with python For deployment, please consider using WSGI (more details here). For example to run using Gunicorn, execute:

gunicorn -b mattermostgithub:app

Alternatively, a Dockerfile is provided to run using Docker (see below).


GitHub messages can be delegated to different Mattermost hooks. The order is as follows:

  • First try to find a hook for the repositories full name.
  • If that fails, try to find a hook for the organisation name.
  • Otherwise use the default hook.

Repositories can be blacklisted by setting them to None instead of (url, channel).

Ignore actions

Specific Github events can be ignored by adding GITHUB_IGNORE_ACTIONS to In the example above labeled and assigned events for issues are ignored, while opened, closed, etc. events will continue to show up on Mattermost.

Server settings

The server is listening by default on address, port 5000, and using / as base route. Make sure to point your Github webhooks to

If you have a proxy/load-balancer in front of your machine, and do not want to expose port 5000 to the outside, change the SERVER['hook'] value and redirect it to this service. For example, if SERVER['hook'] is /hooks/github, your Github webhooks would be


The secret key that can be set when setting up the Github webhook. If you don't want to use a secret, set the field to None.

Deploying with Docker

To deploy with Docker, make sure you have Docker installed and run:

docker build --rm=true -t mm-github .
docker run --rm -v "$(pwd)":/home/app -w /home/app -p 5000:5000 -ti mm-github

If you want to run in background mode, change the option --rm for -d.

Supported Events

Not all Github events are forwarded to Mattermost. Currently supported events are:

  • Ping events (send when first adding the Github webhook)
  • Commit pushes and comments
  • Issues (open, close, comment)
  • Pull Requests (create, merge, remove, comment)
  • Create/Delete repositories
  • Create/Delete branches and tags

All other events will report back to GitHub with 400 Not Implemented.

Known issues

  • Channel names need to use the spelling that is used in their URL (the channel ID), e.g. instead of Town Square it needs to be town-square.

  • If you set a custom username (as shown in the default config), make sure you also set Enable webhooks and slash commands to override usernames under Custom Integrations in the System Console to True. Otherwise the bots username will be that of the person that setup the Mattermost integration.

You can’t perform that action at this time.