Skip to content

Commit ecd8711

Browse files
yasunariwyasunariw
committed
update documentation with new config options
1 parent 29258bd commit ecd8711

File tree

2 files changed

+40
-74
lines changed

2 files changed

+40
-74
lines changed

‎documentation/config_docs.md‎

Lines changed: 30 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
1-
# About
1+
# Repository Configuration
22

3-
Config file is where the variables affecting the behaviour of notabot are defined.
3+
A repository configuration file specifies how notifications should be handled for a given repository. It should be at the root of your monorepo in the main branch. The bot will look for a `notabot.json` file by default, but you can change this behavior with the `--config` flag.
4+
5+
When the bot receives its first incoming GitHub notification, it will query the repository URL to retrieve its configuration file. For subsequent notifications, it will use the cached configuration unless an update is detected.
6+
7+
To update the configuration, simply edit the configuration file and push your changes to GitHub. The bot will detect and apply those changes to the configuration, and will be reflected in the next request onwards.
8+
9+
Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads) for more information on GitHub event payload structure.
410

511
# Configuration values
612

713
**example**
814
```json
915
{
10-
"offline": "github-api-cache",
1116
"main_branch_name": "develop",
1217
"status_rules": {
1318
...
@@ -17,16 +22,13 @@ Config file is where the variables affecting the behaviour of notabot are define
1722
},
1823
"label_rules": {
1924
...
20-
},
21-
"suppress_cancelled_events": true
25+
}
2226
}
2327
```
2428

2529
| value | description | optional | default |
2630
|-|-|-|-|
2731
| `main_branch_name` | main branch used for the repo; filtering notifications about merges of main into other branches | Yes | - |
28-
| `offline` | path to github api data when http calls are not allowed; used for testing | Yes | - |
29-
| `suppress_cancelled_events` | supresses status cancelled events | Yes | `true` |
3032
| `status_rules` | status rules config object | No | - |
3133
| `label_rules` | label rules config object | No | - |
3234
| `prefix_rules` | prefix rules config object | No | - |
@@ -68,38 +70,28 @@ A json object with fields of bools for each status type.
6870
| `cancelled` | provide regex to ignore `failure` notifications with a description that matches it | Yes | - |
6971

7072

71-
## Label Config
73+
## Label Options
7274

73-
Label rules apply to PR and issues notifications.
75+
**Label rules** apply to PR and issue notifications. If a payload matches multiple rules, they are all included.
7476

75-
**example**
77+
**Example**
7678
```json
7779
"label_rules": {
7880
"default_channel": "default",
7981
"rules": [
8082
{
81-
"allow": [
82-
"backend"
83-
],
84-
"ignore": [],
83+
"allow": ["backend"],
8584
"channel": "backend"
8685
},
8786
{
88-
"allow": [
89-
"a1"
90-
],
91-
"ignore": [],
87+
"allow": ["a1"],
9288
"channel": "a1-bot"
9389
},
9490
{
95-
"allow": [
96-
"a3"
97-
],
98-
"ignore": [],
91+
"allow": ["a3"],
9992
"channel": "a3"
10093
},
10194
{
102-
"allow": [],
10395
"ignore": [
10496
"backend",
10597
"a1",
@@ -113,57 +105,52 @@ Label rules apply to PR and issues notifications.
113105

114106
| value | description | optional | default |
115107
|-|-|-|-|
116-
| `default_channel` | default channel to notify if no rules match | Yes | no channels will be notified on default |
108+
| `default_channel` | default channel to notify if no rules match | Yes | None |
117109
| `rules` | list of `label_rule` objects | No | - |
118110

119111
### Label Rule
120112

113+
A **label rule** specifies whether or not a Slack channel should be notified, based on the labels present in the given payload. For each rule, `ignore` is a blacklist of labels that should not notify the rule's channel, and `allow` is a whitelist of labels that should. The `ignore` list takes precedence over the `allow` list. Both are optional; if neither are provided, the rule will always generate a notification for its channel.
114+
121115
| value | description | optional | default |
122116
|-|-|-|-|
123-
| `allow` | whitelist of label values that match this rule; if list is empty it vacuously satisfies the rule | No | - |
124-
| `ignore` | blacklist of label values; any labels matching will not match the rule | No | - |
125-
| `channel` | channel to use as webhook if matching this label rule | No | - |
126-
127-
## Prefix Config
117+
| `allow` | whitelist of label values; if not provided, the rule is vacuously satisfied | Yes | - |
118+
| `ignore` | blacklist of label values; any labels matching will not match the rule | Yes | - |
119+
| `channel` | channel to use as webhook if the rule is matched | No | - |
128120

129-
Prefix rules apply to filenames. If a filename satisfies a prefix rule, the rule's channel will be notified.
121+
## Prefix Options
130122

131-
The prefix config object is exactly the same as **Label Config** except its `rules` are list of `prefix_rule` objects.
123+
**Prefix rules** apply to push, commit comment, and status notifications. If a filename satisfies a prefix rule, the rule's channel will be notified. If a filename matches multiple rules, only the one that is matched by the *longest prefix* is included.
132124

133-
**example**
125+
**Example**
134126
```json
135127
"prefix_rules": {
136128
"default_channel": "default",
137129
"rules": [
138130
{
139-
"allow": [
140-
"backend/a1"
141-
],
142-
"ignore": [],
131+
"allow": ["backend/a1"],
143132
"channel": "a1"
144133
},
145134
{
146135
"allow": [
147136
"backend/a5",
148137
"backend/a4"
149138
],
150-
"ignore": [],
151139
"channel": "backend"
152140
},
153141
{
154-
"allow": [],
155-
"ignore": [],
156142
"channel": "all-push-events"
157143
}
158144
]
159145
},
160146
```
161147

162-
163148
### Prefix Rule
164149

150+
A **prefix rule** specifies whether or not a Slack channel should be notified, based on the filenames present in the commits associated with the given payload. The semantics for the `allow` and `ignore` fields are the same as those for label rules (see above).
151+
165152
| value | description | optional | default |
166153
|-|-|-|-|
167-
| `allow` | whitelist of strings that if prefixed in the filename matches the rule | No | - |
168-
| `ignore` | blacklist of strings that if prefixed in the filename does not match the rule | No | - |
169-
| `channel` | channel to use as webhook if matching this prefix rule | No | - |
154+
| `allow` | whitelist of file prefixes that match the rule | Yes | - |
155+
| `ignore` | blacklist of file prefixes that do not match the rule | Yes | - |
156+
| `channel` | channel to use as webhook if the rule is matched | No | - |

‎documentation/secret_docs.md‎

Lines changed: 10 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
# About
1+
# Secrets
22

3-
Secret file is where sensitive information such as the urls used for webhooks and other tokens are stored.
3+
A secrets file stores sensitive information. Unlike the repository configuration file, it should not be checked into the monorepo's version control. Instead, store it locally at a location accessible by the bot.
44

5-
# Secret Values
5+
# Options
6+
7+
**Example**
68

7-
**example**
89
```json
910
{
1011
"slack_hooks": [
@@ -42,36 +43,14 @@ Secret file is where sensitive information such as the urls used for webhooks an
4243

4344
| value | description | optional | default |
4445
|-|-|-|-|
45-
| `slack_hooks` | list of webhook config objects | No | - |
46+
| `slack_hooks` | list of channel names (`channel`) and their corresponding webhook endpoint (`url`) | No | - |
4647
| `gh_token` | specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
47-
| `gh_hook_token` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
48+
| `gh_webhook_secret` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
4849

4950
## `gh_token`
5051

51-
### Token generation
52-
53-
Some event notifications (e.g., status, commit comment) require a personal token to be addded to the configuration. To create a personal token, take the following steps:
54-
1. Verify your email address, if needed.
55-
1. In the upper-right corner of any page, click your profile photo, then click **Settings**.
56-
1. In the left sidebar, click **Developer settings**.
57-
1. In the left sidebar, click **Personal access tokens**.
58-
1. Click **Generate new token**.
59-
1. Give your token a descriptive name in the **Note** section.
60-
1. Grant ***repo*** scope.
61-
1. Click **Generate token**.
62-
1. Copy the token to `secrets.json` file in a `gh_token` field.
63-
64-
For more detailed instructions on token generation, refer to https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line.
65-
52+
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.
6653

67-
## `gh_hook_token`
68-
For more information on `gh_hook_token` see [developer.github.com/webhooks/securing](https://developer.github.com/webhooks/securing/)
54+
## `gh_webhook_secret`
6955

70-
## Webhook Config
71-
72-
Channels that are defined in rules in config will be mapped to urls defined in the webhook
73-
74-
| value | description | optional | default |
75-
|-|-|-|-|
76-
| `url` | url to call to send the message | No | - |
77-
| `channel` | name of the channel where the message will be posted as used in config | No | - |
56+
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.

0 commit comments

Comments
 (0)