GitHub plugin for Mattermost
Maintainer: @hanzei Co-Maintainer: @mickmister
A GitHub plugin for Mattermost. Supports GitHub SaaS and Enterprise versions.
This guide is intended for Mattermost System Admins setting up the GitHub plugin, Mattermost users who want information about the plugin functionality, and Mattermost users who want to connect their GitHub account to Mattermost. For more information about contributing to this plugin, visit the Development section.
This repository is licensed under the Apache 2.0 License.
The Mattermost GitHub plugin uses a webhook to connect your GitHub account to Mattermost to listen for incoming GitHub events. Events notifications are via DM in Mattermost. The Events don’t need separate configuration.
After a 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:
/github
slash command. Read more about slash commands here.This guide assumes:
GitHub plugin configuration starts by registering an OAuth app in GitHub and ends in Mattermost.
Note: If you're using GitHub Enterprise, replace all GitHub links below with your GitHub Enterprise URL.
You can use the /github setup
command to streamline the configuration process.
You must first register the Mattermost GitHub Plugin as an authorized OAuth app regardless of whether you're setting up the GitHub plugin as a system admin or a Mattermost user.
Mattermost GitHub Plugin - <your company name>
https://github.com/mattermost/mattermost-plugin-github
https://your-mattermost-url.com/plugins/github/oauth/complete
, replacing https://your-mattermost-url.com
with your Mattermost URL. This value needs to match the Mattermost server URL that you or your users users log in to.Webhook Secret
and At Rest Encryption Key
./github connect
in a Mattermost channel. You should receive a Direct Message from the GitHub plugin about the features available to you.A System Admin performs the remaining steps: 7. Go to System Console > Plugins > GitHub and enter the GitHub OAuth Client ID and GitHub OAuth Client Secret you copied in a previous step. 8. Hit Save.
As a system admin, you must create a webhook for each organization you want to receive notifications for or subscribe to.
https://your-mattermost-url.com/plugins/github/webhook
, replacing https://your-mattermost-url.com
with your Mattermost URL.application/json
Branch or Tag creation
, Branch or Tag deletion
, Issue comments
, Issues
, Pull requests
, Pull request review
, Pull request review comments
, Pushes
, Stars
.If you have multiple organizations, repeat the process starting from step 3 to create a webhook for each organization.
As a System Admin, if you have an existing Mattermost user account with the name github
, the plugin will post using the github
account but without a BOT
tag.
To prevent this, either:
github
user to a bot account by running mattermost user convert github --bot
in the CLI.or
github
.Note: For v0.9.0
and earlier of the GitHub plugin, instead of using bot accounts, set the username the plugin is attached to in System Console > Plugins > GitHub.
Open System Console > Plugins > GitHub and do the following:
true
.https://github.example.com
. The Base and Upload URLs are often the same. 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.You're all set!
Once configuration is complete, run the /github connect
slash command from any channel within Mattermost to connect your Mattermost account with GitHub.
When you’ve tested the plugin and confirmed it’s working, notify your team so they can connect their GitHub account to Mattermost and get started. Copy and paste the text below, edit it to suit your requirements, and send it out.
Hi team,
We've set up the Mattermost GitHub plugin, so you can get notifications from GitHub in Mattermost. To get started, run the
/github connect
slash command from any channel within Mattermost to connect your Mattermost account with GitHub. Then, take a look at the slash commands section for details about how to use the plugin.
Autocomplete slash commands - Explore all the available slash commands by typing /
in the text input box - the autocomplete suggestions help by providing a format example in black text and a short description of the slash command in grey text. Visit the documentation for more details.
Subscribe to a repository - Use /github subscriptions add
to subscribe a Mattermost channel to receive notifications for new pull requests, issues, branch creation, and more in a GitHub repository.
Help Wanted
from mattermost/mattermost-server
, use:/github subscriptions add mattermost/mattermost-server --features issues,pulls,issue_comments,label:"Help Wanted"
--features
: comma-delimited list of one or more of: issues, pulls, pulls_merged, pulls_created, pushes, creates, deletes, issue_creations, issue_comments, pull_reviews, label:"labelname". Defaults to pulls,issues,creates,deletes.--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.--render-style
: notifications will be delivered in the specified style (for example, the body of a pull request will not be displayed). Supported
values are collapsed
, skip-body
or default
(same as omitting the flag).--exclude
: comma-separated list of the repositories to exclude from getting the subscription notifications like mattermost/mattermost-server
. Only supported for subscriptions to an organization.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.
Setup GitHub integration - Use /github setup
to configure the integration between GitHub and Mattermost. This command has the following subcommands:
/github setup oauth
: Sets up the OAuth2 application in GitHub, establishing the necessary authorization connection between GitHub and Mattermost./github setup webhook
: Creates a webhook from GitHub to Mattermost, allowing real-time notifications and updates from GitHub to be sent to Mattermost channels./github setup announce
: Sends a message to designated channels in Mattermost, announcing the availability of the GitHub integration for team members to use.And more! - Run /github help
to see what else the slash command can do.
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.
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 subscriptions add mattermost/mattermost-plugin-github issues,label:"Severity/Critical"
Feel free to create a GitHub issue or join the GitHub Plugin channel on our community Mattermost instance to discuss.
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.
This plugin contains both a server and web app portion. Read our documentation about the Developer Workflow and Developer Setup for more information about developing and extending plugins.
The version of a plugin is determined at compile time, automatically populating a version
field in the plugin manifest:
v
, e.g. 1.3.1
.git rev-parse --short HEAD
, e.g. 1.3.1+d06e53e1
.0.0.0+76081421
.To disable this behaviour, manually populate and maintain the version
field.
In order to get your environment set up to run Playwright tests, please see the setup guide at e2e/playwright.