From 838ae7c170eebd9b1179f30b6dd8dac97aa863d3 Mon Sep 17 00:00:00 2001
From: Yasunari Watanabe <yasunari.watanabe@ahrefs.com>
Date: Mon, 4 Jan 2021 17:06:14 +0800
Subject: [PATCH] update documentation with multi-repo info

---
 README.md                    |  2 +-
 documentation/secret_docs.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 53f8f276..052d0446 100644
--- a/README.md
+++ b/README.md
@@ -50,7 +50,7 @@ You can configure Monorobot to [unfurl GitHub links](https://api.slack.com/refer
 
 ### Documentation
 
-The bot expects two configuration files to be present.
+Add a configuration file to each repository you want to support, and a secrets file on the bot server itself. Read on for instructions to set up each file:
 
 * [Repository configuration](./documentation/config_docs.md)
 * [Secrets](./documentation/secret_docs.md)
diff --git a/documentation/secret_docs.md b/documentation/secret_docs.md
index 87389bce..60ef0a32 100644
--- a/documentation/secret_docs.md
+++ b/documentation/secret_docs.md
@@ -17,6 +17,8 @@ A secrets file stores sensitive information. Unlike the repository configuration
 |-|-|-|-|
 | `gh_token` | specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
 | `gh_hook_token` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
+| `repos` | an object mapping repository URLs to repository-specific GitHub secrets | Yes | - |
+| `allowed_repos` | a whitelist of repository URLs to process payloads for | Yes | all incoming payloads are processed |
 | `slack_access_token` | slack bot access token to enable message posting to the workspace | Yes | try to use webhooks defined in `slack_hooks` instead |
 | `slack_hooks` | list of channel names and their corresponding webhook endpoint | Yes | try to use token defined in `slack_access_token` instead |
 | `slack_signing_secret` | specify to verify incoming slack requests | Yes | - |
@@ -27,10 +29,36 @@ Note that either `slack_access_token` or `slack_hooks` must be defined.
 
 Some operations, such as fetching a config file from a private repository, or the commit corresponding to a commit comment event, require a personal access token. Refer [here](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) for detailed instructions on token generation.
 
+*See `repos` if you need to support multiple repositories that use different tokens.*
+
 ## `gh_hook_token`
 
 Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks) for more information on securing webhooks with a token.
 
+*See `repos` if you need to support multiple repositories that use different tokens.*
+
+## `repos`
+
+If you're using Monorobot for multiple repositories that need different secrets (e.g., one on github.com and another on GitHub Enterprise), you can provide them as an object. Secrets defined here will take precedence over those defined at the top level of the secrets file.
+
+Repository URLs should be fully qualified (include the protocol).
+
+```json
+{
+  "https://github.com/acme/runner" : {
+    "gh_token": "XXX"
+  },
+  "https://git.acme.com/acme/coyote" : {
+    "gh_token": "XXX",
+    "gh_hook_token": "XXX"
+  }
+}
+```
+
+## `allowed_repos`
+
+Use this option to restrict incoming notifications from GitHub to approved repository URLs.
+
 ## `slack_access_token`
 
 Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.