mattermost-plugin-github

Mattermost GitHub Plugin

A GitHub plugin for Mattermost. The plugin is currently in beta and does not yet suport GitHub Enterprise.

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 omeone mentions you, requests your review, comments on or modifies one of your pull requests/issues, or assigns you on GitHub
• Sidebar buttons - stay up-to-date with how many reviews, unread messaages, 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 posts for new pull requests and/or issues in a GitHub repository
  • Get to do items - Use /github todo to get an ephemeral message with items to do in GitHub
  • Update settings - Use /github settings to update your settings for the plugin
  • And more! - Run /github help to see what else the slash command can do
• Supports GitHub Enterprise - Works with SaaS and Enteprise versions of GitHub (Enterprise support added in version 0.6.0)

Installation

Requires Mattermost 5.2 or higher

If you're using GitHub Enterprise, replace all GitHub links below with your GitHub Enterprise URL

1. Install the plugin
   1. Download the latest version of the plugin from the GitHub releases page
   2. In Mattermost, go the System Console -> Plugins -> Management
   3. Upload the plugin
2. Register a GitHub OAuth app
   1. Go to https://github.com/settings/applications/new
      • Use "Mattermost GitHub Plugin - " as the name
      • Use "https://github.com/mattermost/mattermost-plugin-github" as the homepage
      • Use "https://your-mattermost-url.com/plugins/github/oauth/complete" as the authorization callback URL, replacing https://your-mattermost-url.com with your Mattermost URL
      • Submit and copy the Client ID and Secret
   2. In Mattermost, go to System Console -> Plugins -> GitHub
      • Fill in the Client ID and Secret and save the settings
3. Create a GitHub webhook
   1. In Mattermost, go to the System Console -> Plugins -> GitHub and copy the "Webhook Secret"
   2. Go to the settings page of your GitHub organization and click on "Webhooks" in the sidebar
      • Click "Add webhook"
      • Use "https://your-mattermost-url.com/plugins/github/webhook" as the payload URL, replacing https://your-mattermost-url.com with your Mattermost URL
      • Change content type to "application/json"
      • Paste the webhook secret you copied before into the secret field
      • Select the events: Issues, Issue comments, Pull requests, Pull request reviews, and Pull request review comments
   3. Save the webhook
   4. Note for each organization you want to receive notifications for or subscribe to, you must create a webhook
4. Configure a bot account
   1. Create a new Mattermost user, through the regular UI or the CLI with the username "github"
   2. Go to the System Console -> Plugins -> GitHub and select this user in the User setting
   3. Save the settings
5. (Optional) Lock the plugin to a GitHub organization
   • Go to System Console -> Plugins -> GitHub and set the GitHub Organization field to the name of your GitHub organization
6. (Enterprise only) Set your Enterprise URLs
   • Go to System Console -> Plugins -> GitHub and set the Enterprise Base URL and Enterprise Upload URL fields to your GitHub Enterprise URLs, ex: https://github.example.com
   • The Base and Upload URLs are often the same
7. Enable the plugin
   • Go to System Console -> Plugins -> Management and click "Enable" underneat the GitHub plugin
8. Test it out
   • In Mattermost, run the slash command /github connect

Developing

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 localdeploy to deploy the plugin to your local server. You will need to restart the server to get the changes.