GitHub integration for Mattermost.
A server listening for GitHub events via webhooks. These events are relayed to Mattermost after processing and formatting.
- PushEvent
- PullRequestEvent
- PullRequestReviewEvent
- PullRequestReviewCommentEvent
- IssuesEvent
- IssueCommentEvent
- StatusEvent
Feel free to open a pull request or an issue if you need support for an event.
To set this up you will need to do three steps:
- create a Mattermost incoming webhooks
- deploy ghmm somewhere publicly accessible
- add GitHub webhooks
You have several options for deploying ghmm:
- deploy using the Docker image
- deploy on Heroku
- build and deploy yourself
The Mattermost documentation explains how to set this up.
You will get an address which looks similar to this one:
There are two ways to configure the application.
- Using a YAML/JSON configuration file (preferred)
- Using environment variables (limited)
Using a configuration file is the preferred way. You can use environment variables if really necessary, but not everything can be configured that way. This option might become deprecated in the future.
The following example shows the different configuration options.
port: 8000 # Port to start ghmm on (default: `8000`)
logging:
priority: ERROR # Log level (default: `ERROR`)*
github:
secret: alligator3 # Secret you share between GitHub and ghmm (optional)
mattermost:
url: https://mattermost # URL where Mattermost is available
apiKey: xyz # Value at the end of the incoming webhook url
repositories:
UlfS:
channel: general
UlfS/ghmm:
channel: ghmm
bot:
username: Octocat
iconUrl: http://i.imgur.com/fzz0wsH.jpg
_default: # '_default' is a reserved key for events not matching any of the other mappings
channel: tools
You need to provide the configuration file as the first argument of the application.
stack exec ghmm-exe config.yml
* Accepted values:
DEBUG
, INFO
, NOTICE
, WARNING
, ERROR
, CRITICAL
, ALERT
, EMERGENCY
File-based configuration is the preferred way to configure the application.
This configuration method is limited. It does not support mapping repositories to channels and new features will most likely not be supported as well.
Variable | Description |
---|---|
MATTERMOST_URL |
URL where Mattermost is available |
MATTERMOST_API_KEY |
Value at the end of the incoming webhook url |
MATTERMOST_CHANNEL |
Channel to post the messages to (optional) |
GITHUB_SECRET |
Secret you share between GitHub and ghmm (optional) |
PORT |
Port to start ghmm on (default: 8000 ) |
LOG_LEVEL |
Log level (default: ERROR )* |
See config/dev.example
for how this might look like.
Note that this example configuration also includes values for the development scripts, which might not be relevant for you.
* Accepted values:
DEBUG
, INFO
, NOTICE
, WARNING
, ERROR
, CRITICAL
, ALERT
, EMERGENCY
The latest Docker image UlfS/ghmm is available on Docker Hub.
You can easily run the app with the included docker-compose configuration.
. config/dev # loads the configuration / environment variables
docker-compose up -d app # starts the app
Note: You can also build the Docker image yourself using stack.
stack image container # creates a docker image 'ulfs/ghmm'
You need an Heroku account and have the Heroku CLI installed.
Create an app using mfine's buildpack for haskell.
heroku create --buildpack https://github.com/UlfS/heroku-buildpack-stack.git your-app-name
git push heroku master
You need to set the environment mentioned in section 2.1 on Heroku:
heroku config:set MATTERMOST_URL=your.mattermost.server.com
heroku config:set MATTERMOST_API_KEY=your-mattermost-api-key-here
Note: PORT
does not need to be set - it will be set by Heroku.
To deploy the app you need at least one web dyno.
heroku scale web=1
The app is now available at https://your-app-name.herokuapp.com/.
2.2c Build and deploy using stack
Stack automatically downloads GHC and builds the project.
Follow the instructions to install it.
stack build
The output will also tell you where to find the executable.
Note: Building can also be done in a Docker container, see stack's docker integration usage.
You can start the app directly or create a docker container for it and run that.
. config/dev # loads the configuration / environment variables
stack exec ghmm-exe # starts the app on the configured port
If you want to run the app as a docker container, you can build an image using stack
and run the app with the included docker-compose configuration.
stack image container # creates a docker image 'ulfs/ghmm'
. config/dev # loads the configuration
docker-compose up -d app # starts the app on port 8000
Note: There is also a Docker image (UlfS/ghmm) with the latest code on Docker Hub.
If you want to deploy or test it locally, you can use tunneling services such as beame-insta-ssl, ngrok, pagekite or localtunnel.
Note: I personally use beame-insta-ssl, because it works great within different networks and they provide a static address for free. Otherwise you have to delete and add the new address to your GitHub repo(s) every time you restart the process.
There is a page on Github which explains how to do that.
The config.url
must point to where ghmm is available.
Make sure it is publicly accessible.
The config.content_type
must be application/json
.
Optional: Choose a config.secret
that is shared between GitHub and ghmm, so that
strangers can't impersonate GitHub.