Skip to content

Commit b92109d

Browse files
yasunariwyasunariw
committed
update docs
1 parent bc47539 commit b92109d

File tree

2 files changed

+113
-52
lines changed

2 files changed

+113
-52
lines changed

‎README.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,35 @@
1-
# Notabot
1+
# Monorobot
22

3-
Notifications bot server to receive notifications from webhooks and post them to slack
3+
A Slackbot for GitHub monorepos. Configure how repo notifications should be routed to specified Slack channels based on file prefixes, issue/PR labels, and CI build statuses.
44

55
## Setting Up
66

7-
Install dependencies, if needed:
7+
Install dependencies via OPAM.
88

99
```sh
1010
opam install --deps-only .
1111
```
1212

13-
Build with
13+
Then, build with Dune.
1414

1515
```sh
1616
make
1717
```
1818

19-
and use resulting `_build/default/src/notabot.exe` binary.
20-
2119
## Running
2220

23-
At startup time, secrets are read from the local `secrets.json` file. The main configuration is read remotely from a `notabot.json` file in the default branch, and its schema is defined in `lib/notabot.atd`.
21+
Run the `_build/default/src/notabot.exe` binary. The following commands are supported.
22+
23+
- `run`: Launch the HTTP server
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)
2426

2527
### Documentation
2628

27-
* [config](./documentation/config_docs.md)
28-
* [secret](./documentation/secret_docs.md)
29+
The bot expects two configuration files to be present.
30+
31+
* [Repository configuration](./documentation/config_docs.md)
32+
* [Secrets](./documentation/secret_docs.md)
2933

3034
## Testing (development)
3135

‎documentation/config_docs.md‎

Lines changed: 100 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -8,67 +8,30 @@ To update the configuration, simply edit the configuration file and push your ch
88

99
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.
1010

11-
# Configuration values
11+
## Options
1212

13-
**example**
13+
**Example**
1414
```json
1515
{
1616
"main_branch_name": "develop",
17-
"status_rules": {
18-
...
19-
},
2017
"prefix_rules": {
2118
...
2219
},
2320
"label_rules": {
2421
...
22+
},
23+
"status_rules": {
24+
...
2525
}
2626
}
2727
```
2828

2929
| value | description | optional | default |
3030
|-|-|-|-|
3131
| `main_branch_name` | main branch used for the repo; filtering notifications about merges of main into other branches | Yes | - |
32-
| `status_rules` | status rules config object | No | - |
3332
| `label_rules` | label rules config object | No | - |
3433
| `prefix_rules` | prefix rules config object | No | - |
35-
36-
## Status Config
37-
38-
**example**
39-
```json
40-
"status_rules": {
41-
"allowed_pipelines": [
42-
"default",
43-
"buildkite/pipeline2"
44-
],
45-
"status": {
46-
"pending": false,
47-
"success": "once",
48-
"failure": true,
49-
"error": true,
50-
"cancelled": "^\\(Build #[0-9]+ canceled by .+\\|Failed (exit status 255)\\)$"
51-
}
52-
},
53-
```
54-
55-
| value | description | optional | default |
56-
|-|-|-|-|
57-
| `title` | if defines a whitelist of values for the github payload. If not specified, all is permitted. | Yes | - |
58-
| `status` | a `status_state` config object | No | - |
59-
60-
### Status State
61-
62-
A json object with fields of bools for each status type.
63-
64-
| value | description | optional | default |
65-
|-|-|-|-|
66-
| `pending` | `true` to notify; `false` to ignore | No | - |
67-
| `success` | `true` to notify; `false` to notify all; `"once"` to notify the first and ignore subsequent consecutive successes| No | - |
68-
| `failure` | `true` to notify; `false` to ignore | No | - |
69-
| `error` | `true` to notify; `false` to ignore | No | - |
70-
| `cancelled` | provide regex to ignore `failure` notifications with a description that matches it | Yes | - |
71-
34+
| `status_rules` | status rules config object | No | - |
7235

7336
## Label Options
7437

@@ -163,3 +126,97 @@ A **prefix rule** specifies whether or not a Slack channel should be notified, b
163126
| `allow` | if commit files match any prefix in this list, they should be routed to the channel | Yes | all prefixes allowed if no list provided |
164127
| `ignore` | if commit files match any prefix in this list, they shouldn't be routed to the channel (even if they match any allow prefixes) | Yes | - |
165128
| `channel` | channel to use as webhook if the rule is matched | No | - |
129+
130+
## Status Options
131+
132+
Monorobot supports additional behavior for GitHub status notifications, which are typically triggered by CI builds. A payload of this type contains:
133+
134+
- A `context` field, whose value is the name of the CI pipeline the notificiation is about
135+
- A `state` field, whose value is either `success`, `failure`, `pending`, or `error`
136+
137+
The following takes place when a status notification is received.
138+
139+
1. Check whether a status notification should be *allowed* for further processing or *ignored*, according to a list of **status rules**. The bot will check the list *in order*, and use the policy defined by the first rule that the notification satisfies. If no rule matches, the default behavior is to allow the notification.
140+
1. For those payloads allowed by step 1, if it isn't a main branch build notification, route to the default channel to reduce spam in topic channels. Otherwise, check the notification commit's files according to the prefix rules.
141+
142+
Internally, the bot keeps track of the status of the last allowed payload, for a given pipeline and branch. This information is used to evaluate the status rules (see below).
143+
144+
**Example**
145+
146+
```json
147+
"status_rules": {
148+
"allowed_pipelines": [
149+
"default",
150+
"buildkite/pipeline2"
151+
],
152+
"rules": [
153+
{
154+
"on": ["failure"],
155+
"when": {
156+
"match": {
157+
"field": "description",
158+
"re": "^\\(Build #[0-9]+ canceled by .+\\|Failed (exit status 255)\\)$"
159+
}
160+
},
161+
"policy": "ignore"
162+
},
163+
{ "on": ["pending"], "policy": "ignore"},
164+
{ "on": ["failure", "error"], "policy": "allow"},
165+
{ "on": ["success"], "policy": "allow_once"}
166+
]
167+
}
168+
```
169+
170+
| value | description | optional | default |
171+
|-|-|-|-|
172+
| `allowed_pipelines` | a list of pipeline names; if specified, payloads whose pipeline name is not in the list will be ignored immediately, without checking the **status rules**; otherwise, all pipelines will be included in the status rule check | Yes | - |
173+
| `rules` | a list of **status rules** to determine whether to *allow* or *ignore* a payload for further processing | No | - |
174+
175+
### Status Rules
176+
177+
A **status rule** specifies whether a GitHub status notification should generate a Slack notification, given the notification's status and the last allowed build status. There are three policy options for handling payloads:
178+
179+
- `allow`: Notify every time.
180+
- `ignore`: Suppress every time.
181+
- `allow_once`: Only notify if the last allowed status notification's build status for the given pipeline and branch differs from the current one. Useful for suppressing consecutive build success notifications.
182+
183+
For example, the rule:
184+
```
185+
{ "on": A, "when": B, "policy": C }
186+
```
187+
is interpreted as:
188+
189+
> "on a notification with a build state in `A`, when condition `B` is met, adopt the policy `C`".
190+
191+
| value | description | optional | default |
192+
|-|-|-|-|
193+
| `on` | a list of build states that can trigger this rule | No | - |
194+
| `when` | a **status condition** object which, if specified, must be true for the rule to match | Yes | - |
195+
| `policy` | a policy option (one of `allow`, `ignore`, `allow_once`) | No | - |
196+
197+
### Status Conditions
198+
199+
You can optionally provide a **status condition** to specify additional requirements that a notification payload should meet, in order for a status rule's policy to apply.
200+
201+
- `all_of`: Matches if every sub-condition in a list is true. Value should be the list of sub-conditions.
202+
- `one_of`: Matches if at least one sub-condition in a list is true. Value should be the list of sub-conditions.
203+
```json
204+
{
205+
"all_of/one_of": [ condition1, condition2, ...]
206+
}
207+
```
208+
- `not`: Matches if a sub-condition is false. Value should be the sub-condition.
209+
```json
210+
{
211+
"not": condition
212+
}
213+
```
214+
- `match`: Matches a text field in the payload against a regular expression. Value should be an object of the form:
215+
```json
216+
{
217+
"match": {
218+
"field": "context" | "description" | "sha" | "target_url",
219+
"re": string // a regular expression
220+
}
221+
}
222+
```

0 commit comments

Comments
 (0)