Add documentation on slack mentions

README.md

@@ -54,6 +54,12 @@ Note: The `slack_access_token` must be configured in your secrets file for link
 1. Configure your app to [support the Events API](https://api.slack.com/events-api#prepare). During the [url verification handshake](https://api.slack.com/events-api#the-events-api__subscribing-to-event-types__events-api-request-urls__request-url-configuration--verification__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.
 1. [Register the GitHub domains](https://api.slack.com/reference/messaging/link-unfurling#configuring_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](./documentation/config_docs.md) 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:

documentation/config_docs.md

@@ -18,6 +18,10 @@ Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks
     "ignored_users": [
         "ignored_user"
     ],
+    "user_mappings": {
+        "[email protected]": "[email protected]",
+        "gh-handle": "[email protected]"
+    },
     "prefix_rules": {
         ...
     },
@@ -41,6 +45,11 @@ Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks
 | `status_rules` | status rules config object | all status notifications are ignored |
 | `project_owners` | project owners config object | no project owners are defined |
 | `ignored_users` | list of users to be ignored on all notifications | no user is ignored |
+| `user_mappings` | list of mappings from git email and/or GitHub handle to Slack email | no mapping defined
+
+Note that in `user_mappings`, git email to Slack email mappings are used for status DMs, while GitHub handle to Slack email mappings are used to get Slack mentions in comment notifications.
+
+The reason for these two separate Slack email matching schemes is that in the case of commits, the git email is available in the GitHub payload and can be used to directly match with Slack emails for status DMs (`user_mappings` can be used to manually override if there is a known mismatch between git email and Slack email). However, for actions done on GitHub itself (e.g. opening PRs, commenting, etc.), usually the only thing available is the GitHub username. To get the email in these cases, a user will have to go to settings and set their email to public, which is (1) hard to enforce if there are many working on the monorepo, and (2) might be undesirable for privacy reasons.
 
 ## Label Options