Mattermost GitHub Plugin
Maintainer: @hanzei Co-Maintainer: @larkox
A GitHub plugin for Mattermost. Supports GitHub SaaS and Enterprise versions.
Features
After your System Admin has configured the GitHub plugin, run /github connect
in a Mattermost channel to connect your Mattermost and GitHub accounts.
Once connected, you'll have access to the following features:
- Daily reminders - the first time you log in to Mattermost each day, get a post letting you know what issues and pull requests need your attention
- Notifications - get a direct message in Mattermost when someone mentions you, requests your review, comments on or modifies one of your pull requests/issues, or assigns you on GitHub
- Post actions - create a GitHub issue from a post or attach a post message to an issue
- hover over a post to reveal the post actions menu and click the More Actions (...) option
- Sidebar buttons - stay up-to-date with how many reviews, unread messages, assignments and open pull requests you have with buttons in the Mattermost sidebar
- Slash commands - interact with the GitHub plugin using the
/github
slash command- Subscribe to a respository - Use
/github subscribe
to subscribe a Mattermost channel to receive notifications for new pull requests, issues, branch creation and more in a GitHub repository.-
For instance, to post notifications for issues, issue comments and pull requests matching the label
Help Wanted
frommattermost/mattermost-server
, use/github subscribe mattermost/mattermost-server issues,pulls,issue_comments,label:"Help Wanted"
-
The following flags are supported:
--exclude-org-member
: events triggered by organization members will not be delivered. It will be locked to the organization provided in the plugin configuration and it will only work for users whose membership is public. Note that organization members and collaborators are not the same.
-
- Get to do items - Use
/github todo
to get an ephemeral message with items to do in GitHub, including a list of unread messages and pull requests awaiting your review - Update settings - Use
/github settings
to update your settings for notifications and daily reminders - And more! - Run
/github help
to see what else the slash command can do
- Subscribe to a respository - Use
Installation
In Mattermost 5.12 and later, the GitHub plugin is pre-packaged and no steps are required for installation. You can go directly to Configuration.
In Mattermost 5.11 and earlier, follow these steps:
- Go to https://github.com/mattermost/mattermost-plugin-github/releases to download the latest release file in zip or tar.gz format.
- Upload the file through System Console > Plugins > Management, or manually upload it to the Mattermost server under plugin directory. See documentation for more details.
Configuration
If you are using GitHub Enterprise, replace all GitHub links below with your GitHub Enterprise URL
Step 1: Register an OAuth application in GitHub
-
Go to https://github.com/settings/applications/new to register an OAuth app.
-
Set the following values:
- Application Name:
Mattermost GitHub Plugin - <your company name>
- Homepage URL:
https://github.com/mattermost/mattermost-plugin-github
- Authorization callback URL:
https://your-mattermost-url.com/plugins/github/oauth/complete
, replacinghttps://your-mattermost-url.com
with your Mattermost URL.
- Application Name:
-
Submit. Copy the Client ID and Client Secret in the resulting screen.
-
Go to System Console > Plugins > GitHub and enter GitHub OAuth Client ID and GitHub OAuth Client Secret you copied in a previous step.
Note: If you are running Mattermost v5.11 or earlier, you must first go to the releases page of this GitHub repository, download the latest release, and upload it to your Mattermost instance following this documentation.
-
Hit Save.
Step 2: Create a webhook in GitHub
-
In System Console > Plugins > GitHub, generate a new value for Webhook Secret. Copy it as you will use it in a later step.
-
Hit Save to save the secret.
-
Go to the Settings page of your GitHub organization you want to send notifications from, then select Webhooks in the sidebar.
Note: You must create a webhook for each organization you want to receive notifications for or subscribe to.
-
Click Add webhook
-
Set the following values:
- Payload URL:
https://your-mattermost-url.com/plugins/github/webhook
, replacinghttps://your-mattermost-url.com
with your Mattermost URL - Content Type:
application/json
- Secret: the webhook secret you copied previously
- Payload URL:
-
Select Let me select individual events for "Which events would you like to trigger this webhook?", then select the following events:
Branch or Tag creation
,Branch or Tag deletion
,Issue comments
,Issues
,Pull requests
,Pull request review
,Pull request review comments
,Pushes
-
Hit Add Webhook to save it.
Step 3: Configure plugin in Mattermost
- If you have an existing user account with the name
github
, either:
- convert the
github
user to a bot account by runningmattermost user convert github --bot
in the CLI, or - if the user is an existing user account you want to preserve, change its username and restart the Mattermost server, after which the plugin will create a bot account with the name
github
.
If you don't take either action, the plugin will post using the github
account but without a BOT
tag.
Note: For versions 0.9 and earlier of the GitHub plugin, instead of using bot accounts, set the username the plugin is attached to in System Console > Plugins > GitHub.
- Go to System Console > Plugins > GitHub and do the following:
-
Generate a new value for At Rest Encryption Key.
-
(Optional) GitHub Organization: Lock the plugin to a single GitHub organization by setting this field to the name of your GitHub organization.
-
(Optional) Enable Private Repositories: Allow the plugin to receive notifications from private repositories by setting this value to true. When enabled, existing users must reconnect their accounts to gain access to private repositories. Affected users will be notified by the plugin once private repositories are enabled.
-
(Enterprise only) Enterprise Base URL and Enterprise Upload URL: Set these values to your GitHub Enterprise URLs, e.g.
https://github.example.com
. The Base and Upload URLs are often the same.
- Hit Save.
- Go to System Console > Plugins > Management and click Enable to enable the GitHub plugin.
You're all set! To test it, run the /github connect
slash command to connect your Mattermost account with GitHub.
Configuration Notes in HA
If you are running Mattermost v5.11 or earlier in High Availability mode, please review the following:
- To install the plugin, use these documented steps
- Then, modify the config.json using the standard doc steps to the following
"PluginSettings": {
...
"Plugins": {
"github": {
"encryptionkey": "<your encryption key, from step 5 above>",
"githuboauthclientid": "<your oauth client id, from step 2 above>",
"githuboauthclientsecret": "<your oauth client secret, from step 2 above>",
"githuborg": "<your github org>",
"webhooksecret": "<your webhook secret, from step 3 above>"
},
...
"PluginStates": {
...
"github": {
"Enable": true
},
...
}
},
Development
This plugin contains both a server and web app portion.
Use make dist
to build distributions of the plugin that you can upload to a Mattermost server.
Use make check-style
to check the style.
Use make deploy
to deploy the plugin to your local server. Before running make deploy
you need to set a few environment variables:
export MM_SERVICESETTINGS_SITEURL=http://localhost:8065
export MM_ADMIN_USERNAME=admin
export MM_ADMIN_PASSWORD=password
Frequently Asked Questions
How do I connect a repository instead of an organization?
Set up your GitHub webhook from the repository instead of the organization. Notifications and subscriptions will then be sent only for repositories you create webhooks for.
The reminder and /github todo
will still search the whole organization, but only list items assigned to you.
How do I send notifications when a certain label is applied?
Suppose you want to send notifications to a Mattermost channel when Severity/Critical
label is applied to any issue in the mattermost/mattermost-plugin-github
repository. Then, use this command to subscribe to these notifications:
/github subscribe mattermost/mattermost-plugin-github issues,label:"Severity/Critical"
How do I share feedback on this plugin?
Feel free to create a GitHub issue or join the GitHub Plugin channel on our community Mattermost instance to discuss.
How does the plugin save user data for each connected GitHub user?
GitHub user tokens are AES encrypted with an At Rest Encryption Key configured in the plugin's settings page. Once encrypted, the tokens are saved in the PluginKeyValueStore
table in your Mattermost database.