You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+17-1
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,23 @@ Run the `_build/default/src/monorobot.exe` binary. The following commands are su
22
22
23
23
-`run`: Launch the HTTP server
24
24
-`check_gh <GH_PAYLOAD>`: read a Github notification from a file and display the actions that will be taken (used for testing)
25
-
-`check_slack <SLACK_PAYLOAD> <SLACK_WEBHOOK>`: read a Slack notification from a file and send it to a webhook (used for testing)
25
+
-`check_slack <SLACK_PAYLOAD>`: read a Slack notification from a file and send it to a channel (used for testing)
26
+
27
+
## Getting Started
28
+
29
+
1. Commit a **repository configuration** file to the root of your target repository.
30
+
2. Place a **secrets** file locally on the server.
31
+
3. Configure GitHub
32
+
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.
33
+
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`.
34
+
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.
35
+
4. Configure Slack
36
+
1.[Create a Slack app](https://api.slack.com/apps?new_app=1).
37
+
2. Click "Install to Workspace", and when prompted to grant permissions to your workspace, click "Allow".
38
+
3. Set up notifications with one of the following methods:
39
+
-**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.
40
+
-**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.
Copy file name to clipboardexpand all lines: documentation/secret_docs.md
+32-31
Original file line number
Diff line number
Diff line change
@@ -8,44 +8,19 @@ A secrets file stores sensitive information. Unlike the repository configuration
8
8
9
9
```json
10
10
{
11
-
"slack_hooks": [
12
-
{
13
-
"url": "https://slack_webhook_url",
14
-
"channel": "default"
15
-
},
16
-
{
17
-
"url": "https://slack_webhook_url",
18
-
"channel": "aa"
19
-
},
20
-
{
21
-
"url": "https://slack_webhook_url",
22
-
"channel": "backend"
23
-
},
24
-
{
25
-
"url": "https://slack_webhook_url",
26
-
"channel": "all-push-events"
27
-
},
28
-
{
29
-
"url": "https://slack_webhook_url",
30
-
"channel": "frontend-bot"
31
-
},
32
-
{
33
-
"url": "https://slack_webhook_url",
34
-
"channel": "aa-git"
35
-
},
36
-
{
37
-
"url": "https://slack_webhook_url",
38
-
"channel": "siren"
39
-
}
40
-
]
11
+
"gh_token": "",
12
+
"slack_access_token": ""
41
13
}
42
14
```
43
15
44
16
| value | description | optional | default |
45
17
|-|-|-|-|
46
-
|`slack_hooks`| list of channel names (`channel`) and their corresponding webhook endpoint (`url`) | No | - |
47
18
|`gh_token`| specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
48
19
|`gh_hook_token`| specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
20
+
|`slack_access_token`| slack bot access token to enable message posting to the workspace | Yes | try to use webhooks defined in `slack_hooks` instead |
21
+
|`slack_hooks`| list of channel names and their corresponding webhook endpoint | Yes | try to use token defined in `slack_access_token` instead |
22
+
23
+
Note that either `slack_access_token` or `slack_hooks` must be defined.
49
24
50
25
## `gh_token`
51
26
@@ -54,3 +29,29 @@ Some operations, such as fetching a config file from a private repository, or th
54
29
## `gh_hook_token`
55
30
56
31
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.
32
+
33
+
## `slack_access_token`
34
+
35
+
Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.
36
+
37
+
## `slack_hooks`
38
+
39
+
*Note: If `slack_access_token` is also defined, the bot will authenticate over Slack's Web API and this option will not be used.*
40
+
41
+
Expected format:
42
+
43
+
```json
44
+
[
45
+
{
46
+
"channel": "channel name",
47
+
"url": "webhook url"
48
+
},
49
+
{
50
+
"channel": "channel name",
51
+
"url": "webhook url"
52
+
},
53
+
...
54
+
]
55
+
```
56
+
57
+
Refer [here](https://api.slack.com/messaging/webhooks) for obtaining a webhook for a channel.
0 commit comments