Monorobot

A Slackbot for GitHub monorepos. Configure how repo notifications should be routed to specified Slack channels based on file prefixes, issue/PR labels, and CI build statuses.

Check out the accompanying blog post for an overview of Monorobot.

Setting Up

Install via OPAM:

opam install monorobot

Or install dependencies and build locally:

opam install --deps-only .
make

Running

Run the _build/default/src/monorobot.exe binary. The following commands are supported.

• run: Launch the HTTP server
• check_gh <GH_PAYLOAD>: read a Github notification from a file and display the actions that will be taken (used for testing)
• check_slack <SLACK_PAYLOAD>: read a Slack notification from a file and send it to a channel (used for testing)

Getting Started

1. Commit a repository configuration file to the root of your target repository.
2. Place a secrets file locally on the server.
3. Configure GitHub
   1. If targeting a private repository, set up a personal access token with repo scope and store it in the gh_token field of the secrets file. To use the "Project Owners" feature, the token owner must have triage role or above for the repository.
   2. Create a webhook for the repository you are targeting. Set the Payload URL to be <server_domain>/github.
   3. You can optionally secure the webhook with a token (e.g. use head -c 30 /dev/urandom | base64), and store it in the gh_hook_secret field of the secrets file.
4. Configure Slack
   1. Create a Slack app.
   2. Click "Install to Workspace", and when prompted to grant permissions to your workspace, click "Allow".
   3. Set up notifications with one of the following methods:
      • Web API (recommended): To use Slack's Web API, click on "OAuth & Permissions" in your app dashboard's sidebar. Give your bot a Bot Token Scope of chat:write (for per-channel authorization) or chat:write.public (for authorization to all channels). Also give chat:write.customize (to show branch name as bot username). If you want to send direct messages, also add the users:read.email scope, whichis necessary to find the user id matching the email of a commit author. Copy the generated bot token (xoxb-XXXX) to the slack_access_token field of your secrets file. This token is used by the bot to authenticate to the workspace, and remains valid until the token is revoked or the app is uninstalled. If you use the chat:write scope, add the bot to each channel you want to notify.
      • Incoming Webhooks: To use incoming webhooks, enable them in your app dashboard and create one for each channel you want to notify. Store them in the slack_hooks field of your secrets file. If you decide to notify additional channels later, you will need to update the secrets file with the new webhooks and restart the server.

Link Unfurling

You can configure Monorobot to unfurl GitHub links in Slack messages. Currently, commit, pull request, and issue links are supported.

Note: The slack_access_token must be configured in your secrets file for link unfurling. See previous section for details.

1. Give your app links:read and links:write permissions.
2. Configure your app to support the Events API. During the url verification handshake, you should tell Slack to direct event notifications to <server_domain>/slack/events. Ensure the server is running before triggering the handshake.
3. Register the GitHub domains you want to support.

Slack mentions

Monorobot will also try to match mentioned GitHub handles (e.g., in PR/issue/commit comments) to Slack emails. Where there is a match between canonicalised GitHub handle and canonicalised Slack email, the GitHub mention in Monorobot's notification will be replaced with a Slack mention. This feature requires slack_access_token to be configured, and your app must also have the users:read permission. See the previous section for how to set this up.

If your canonicalised GitHub handle is different from your canonicalised Slack email, or if you want to override this default matching scheme, you can create a manual mapping in your repository configuration under the user_mappings option. See the documentation for details.

Documentation

Commit a configuration file to the root of each repository you want to support, and add a secrets file on the bot server itself. Read on for instructions to set up each file:

• Repository configuration
• Secrets

Testing (development)

curl -X POST \
  http://localhost:8080/github \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: {whatever user agent you define}' \
  -H 'X-Github-Event: pull_request' \
  -H 'X-Hub-Signature: {a signature value you define}' \
  -H 'cache-control: no-cache' \
  -d @mock_payloads/pr_notification.json

There are more payloads which will use a different X-Github-Event signature:

pull_request => mock_payloads/pr_notification.json
push => mock_payloads/push_notification.json
check_suite => mock_payloads/ci_notification.json