Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Modularize dependencies for GH payload consumption and Slack message sending #92

Merged
merged 17 commits into from
Dec 24, 2020
Merged

Modularize dependencies for GH payload consumption and Slack message sending #92

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
f06a386
rename gh_webhook_secret and update config.atd comments
yasunariw Dec 19, 2020
9202ce2
extract minimal interface for communicating w/ slack and GH
yasunariw Dec 19, 2020
be8ad60
refactor prefix + label rule checking
yasunariw Dec 19, 2020
17fe0e6
switch fully to new context structure (breaks tests)
yasunariw Dec 19, 2020
cce7469
make Action a functor that consumes GH and Slack api modules (fixes t…
yasunariw Dec 19, 2020
cfb008a
update documentation with new config options
yasunariw Dec 19, 2020
2b291a1
remove dead code
yasunariw Dec 19, 2020
e9e44b1
reapply minor changes that escaped rebase
yasunariw Dec 20, 2020
3abd4c4
edit context structure and define getters for secrets+config
yasunariw Dec 20, 2020
32621f9
generalize shared http request code
yasunariw Dec 20, 2020
e59c186
use consistent config filename
yasunariw Dec 22, 2020
86bd8c8
bubble up nested error reasons to the toplevel handler
yasunariw Dec 22, 2020
ab23e00
restore behavior to print config when it is refreshed
yasunariw Dec 22, 2020
dc00f53
revert differentiation of empty allow/ignore list from undefined list
yasunariw Dec 23, 2020
d21b7e3
use synchronous I/O for local file manipulation for simplicity
yasunariw Dec 23, 2020
6f0471c
preserve results interface after switching to synchronous file I/O
yasunariw Dec 24, 2020
66916a5
remove semantically redundant empty lists
yasunariw Dec 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 26 additions & 23 deletions documentation/config_docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,18 @@
# About
# Repository Configuration

Config file is where the variables affecting the behaviour of notabot are defined.
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.
yasunariw marked this conversation as resolved.
Show resolved Hide resolved

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.

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.

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.

# Configuration values

**example**
```json
{
"offline": "github-api-cache",
"main_branch_name": "develop",
"status_rules": {
...
Expand All @@ -17,16 +22,13 @@ Config file is where the variables affecting the behaviour of notabot are define
},
"label_rules": {
...
},
"suppress_cancelled_events": true
}
}
```

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


## Label Config
## Label Options

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

**example**
**Example**
```json
"label_rules": {
"default_channel": "default",
Expand Down Expand Up @@ -113,24 +115,24 @@ Label rules apply to PR and issues notifications.

| value | description | optional | default |
|-|-|-|-|
| `default_channel` | default channel to notify if no rules match | Yes | no channels will be notified on default |
| `default_channel` | default channel to notify if no rules match | Yes | don't notify any channel |
| `rules` | list of `label_rule` objects | No | - |

### Label Rule

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. If a label exists in both lists, the `ignore` list takes precedence. If an empty `ignore` list is provided, nothing is ignored. If an empty `allow` list is provided, everything is allowed. Both are optional; if neither are provided, the rule will always generate a notification for its channel.

| value | description | optional | default |
|-|-|-|-|
| `allow` | whitelist of label values that match this rule; if list is empty it vacuously satisfies the rule | No | - |
| `ignore` | blacklist of label values; any labels matching will not match the rule | No | - |
| `channel` | channel to use as webhook if matching this label rule | No | - |

## Prefix Config
| `allow` | if notifications match any label in this list, they should be routed to the channel | Yes | all labels allowed if no list provided |
| `ignore` | if notifications match any label in this list, they shouldn't be routed to the channel (even if they match any allow labels) | Yes | - |
| `channel` | channel to use as webhook if the rule is matched | No | - |

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

The prefix config object is exactly the same as **Label Config** except its `rules` are list of `prefix_rule` objects.
**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.

**example**
**Example**
```json
"prefix_rules": {
"default_channel": "default",
Expand Down Expand Up @@ -159,11 +161,12 @@ The prefix config object is exactly the same as **Label Config** except its `rul
},
```


### Prefix Rule

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).

| value | description | optional | default |
|-|-|-|-|
| `allow` | whitelist of strings that if prefixed in the filename matches the rule | No | - |
| `ignore` | blacklist of strings that if prefixed in the filename does not match the rule | No | - |
| `channel` | channel to use as webhook if matching this prefix rule | No | - |
| `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 |
| `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 | - |
| `channel` | channel to use as webhook if the rule is matched | No | - |
37 changes: 8 additions & 29 deletions documentation/secret_docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# About
# Secrets

Secret file is where sensitive information such as the urls used for webhooks and other tokens are stored.
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.

# Secret Values
# Options

**Example**

**example**
```json
{
"slack_hooks": [
Expand Down Expand Up @@ -42,36 +43,14 @@ Secret file is where sensitive information such as the urls used for webhooks an

| value | description | optional | default |
|-|-|-|-|
| `slack_hooks` | list of webhook config objects | No | - |
| `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 | - |

## `gh_token`

### Token generation

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:
1. Verify your email address, if needed.
1. In the upper-right corner of any page, click your profile photo, then click **Settings**.
1. In the left sidebar, click **Developer settings**.
1. In the left sidebar, click **Personal access tokens**.
1. Click **Generate new token**.
1. Give your token a descriptive name in the **Note** section.
1. Grant ***repo*** scope.
1. Click **Generate token**.
1. Copy the token to `secrets.json` file in a `gh_token` field.

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.

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.
yasunariw marked this conversation as resolved.
Show resolved Hide resolved

## `gh_hook_token`
For more information on `gh_hook_token` see [developer.github.com/webhooks/securing](https://developer.github.com/webhooks/securing/)

## Webhook Config

Channels that are defined in rules in config will be mapped to urls defined in the webhook

| value | description | optional | default |
|-|-|-|-|
| `url` | url to call to send the message | No | - |
| `channel` | name of the channel where the message will be posted as used in config | No | - |
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.
Loading