update docs with slack access token setup and secrets file changes

README.md

@@ -22,7 +22,23 @@ Run the `_build/default/src/monorobot.exe` binary. The following commands are su
 
 - `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> <SLACK_WEBHOOK>`: read a Slack notification from a file and send it to a webhook (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](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token) with `repo` scope and store it in the `gh_token` field of the secrets file.
+    2. [Create a webhook](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/creating-webhooks#setting-up-a-webhook) for the repository you are targeting. Set the *Payload URL* to be `<server_domain>/github`.
+    3. You can optionally [secure the webhook](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks) with a token, and store it in the `gh_hook_token` field of the secrets file.
+4. Configure Slack
+    1. [Create a Slack app](https://api.slack.com/apps?new_app=1).
+    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](https://api.slack.com/web), click on "OAuth & Permissions" in your app dashboard's sidebar. Give your bot a *Bot Token Scope* of `chat:write`. Copy the generated OAuth access 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.
+        - **Incoming Webhooks:** To use [incoming webhooks](https://api.slack.com/messaging/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.
+
 
 ### Documentation
 

documentation/config_docs.md

@@ -86,7 +86,7 @@ A **label rule** specifies whether or not a Slack channel should be notified, ba
 |-|-|-|-|
 | `match` | if notifications have any label in this list, they should be routed to the channel | Yes | all labels matched if no list provided |
 | `ignore` | if notifications have any label in this list, they shouldn't be routed to the channel (even if they have any `match` labels) | Yes | - |
-| `channel` | channel to use as webhook if the rule is matched | No | - |
+| `channel` | channel to notify if the rule is matched | No | - |
 
 ## Prefix Options
 
@@ -125,7 +125,7 @@ A **prefix rule** specifies whether or not a Slack channel should be notified, b
 |-|-|-|-|
 | `match` | if commit files have any prefix in this list, they should be routed to the channel | Yes | all prefixes matched if no list provided |
 | `ignore` | if commit files have any prefix in this list, they shouldn't be routed to the channel (even if they have any `match` prefixes) | Yes | - |
-| `channel` | channel to use as webhook if the rule is matched | No | - |
+| `channel` | channel to notify if the rule is matched | No | - |
 
 ## Status Options
 

documentation/secret_docs.md

@@ -8,44 +8,19 @@ A secrets file stores sensitive information. Unlike the repository configuration
 
 ```json
 {
-    "slack_hooks": [
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "default"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "aa"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "backend"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "all-push-events"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "frontend-bot"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "aa-git"
-        },
-        {
-            "url": "https://slack_webhook_url",
-            "channel": "siren"
-        }
-    ]
+    "gh_token": "",
+    "slack_access_token": ""
 }
 ```
 
 | value | description | optional | default |
 |-|-|-|-|
-| `slack_hooks` | list of channel names (`channel`) and their corresponding webhook endpoint (`url`) | No | - |
 | `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 | - |
+| `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 |
+
+Note that either `slack_access_token` or `slack_hooks` must be defined.
 
 ## `gh_token`
 
@@ -54,3 +29,29 @@ Some operations, such as fetching a config file from a private repository, or th
 ## `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.
+
+## `slack_access_token`
+
+Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.
+
+## `slack_hooks`
+
+*Note: If `slack_access_token` is also defined, the bot will authenticate over Slack's Web API and this option will not be used.*
+
+Expected format:
+
+```json
+[
+    {
+        "channel": "channel name",
+        "url": "webhook url"
+    },
+    {
+        "channel": "channel name",
+        "url": "webhook url"
+    },
+    ...
+]
+```
+
+Refer [here](https://api.slack.com/messaging/webhooks) for obtaining a webhook for a channel.