Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors

Mattermost Plugin GitHub v2.1.2 (optional, connection set up by user is required)

3 years ago
sysadmin
5 minutes

With this plugin, you can set up a Minerva Messenger channel to receive updates on specified GitHub repositories, e.g. with new comments, pull requests, etc.

Connect to GitHub

  • To connect your Minerva Messenger (MM) account to your GitHub account via the plugin, click on the GitHub icon on the bottom left of the MM window or type from any channel
/github connect
  • Private repositories have been enabled for this plugin. Optional: If you want to allow the plugin to work with private repositories, users must connect to their GitHub account by typing
/github connect private
  • You will be re-directed to a GitHub sign-in interface

Note: The Max Planck Digital Library and the Minerva Messenger Service only provide an interface for the use of the Third Party-Plugins. Legal provisions of third parties may apply in the context of the use of the Third Party-Plugins.

  • The GitHub plugin bot will welcome the user in the ‘Direct Messages’ section to provide information about user interface, notifications, slash commands, etc. It may be helpful to either pin or save this post via the post menu for later reference.

 

Getting started

1. About the GitHub Plugin

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 posted message to an issue. Hover over a post to reveal the post actions menu and click More Actions (…).
  • Sidebar buttons – Stay up-to-date with how many reviews, unread messages, assignments, and open pull requests you have with buttons in the left Mattermost sidebar.

2. Slash Commands

Interact with the GitHub plugin using the /github slash command. Read more about slash commands here.

  • 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 executing commands documentation for more details.
  • Get to do items – to get an ephemeral message with items to do in GitHub, including a list of unread messages and pull requests awaiting your review, type/github todo
  • Update settings – to update your settings for notifications and daily reminders, type/github settings
  • And more! – to see what else the slash command can do, type/github help

 

Setting up GitHub repositories for use in Mattermost channels

For basic functions (sending items to GitHub), connecting your Minerva Messenger account to GitHub is sufficient.

For advanced functions (sending to and receiving items from GitHub) you need to set up your connection settings on both sides, GitHub and Minerva Messenger, these settings should match. The Mattermost GitHub plugin uses a webhook to connect your GitHub account to Minerva Messenger to listen for incoming GitHub events. GitHub is responsible for sending the messages, so make sure to include the items you want to receive. In Minerva Messenger, you must specify, which messages you want to show. Note that GitHub can send many more messages than the Mattermost plugin can handle.

1. Configure the GitHub repository – Individual user 

  • Go to the Settings page of your GitHub – repository or organization – you want to send notifications from, then select ‘Webhooks’ in the sidebar.
  • Click ‘Add Webhook’.
  • Set the following values:
  1. Payload URL: https://minervamessenger.mpdl.mpg.de/plugins/github/webhook
  2. Content Type: application/json
  3. Secret: Please request this information from the Minerva Messenger Team by email: minervamessenger [a] mpdl [dot] mpg [dot] de
  • Select ‘Let me select individual events for “Which events would you like to trigger this webhook?”.
  • 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. (Setting more options has no effect since Mattermost will not handle these messages)
  • Hit ‘Add Webhook’ to save it.

2. Configuration – Access to GitHub Organization resources

If you are a member of a Github Organization you may have (or have not) access to Organization resources via the Minerva Messenger OAuth App. If you want to alter the current access settings, reach out to the Organization’s owner.

GitHub OAuth App access restrictions allow organization owners to restrict an app’s access to the organization’s data. Organization members can then use OAuth Apps for their personal user accounts while keeping organization data safe. Read more on the GitHub website.

3. Configure the Plugin in Minerva Messenger in a specific channel

Go to the MM channel where you want to receive the GitHub messages.

Please handle subscriptions carefully, e.g. only subscribe to dedicated MM channels to receive information from GitHub repositories. Handle access permissions carefully: only subscribe to MM channels to receive information from private GitHub repositories, if all channel members have appropriate permissions to view this information.

  • Subscribe to a repository – to subscribe to a channel to receive notifications for new pull requests, issues, branch creation, and more in a GitHub repository, type
/github subscriptions add 
    • For instance, to post notifications for issues, issue comments, and pull requests matching the label Help Wanted from mattermost/mattermost-server, use:
/github subscriptions add mattermost/mattermost-server issues,pulls,issue_comments,label:"Help Wanted"
  • The available options can be found by typing
/github help

 

For more info, please take a look at FAQ.

 

 

References

Documentation – Plugin GitHub

Plugin License – Plugin GitHub

Mattermost Documentation

Github Documentation

Please note: The Max Planck Digital Library and the Minerva Messenger Service only provide an interface for the use of the Third Party-Plugins. Legal provisions of third parties may apply in the context of the use of the Third Party-Plugins.