Skip to content

Commit

Permalink
update documentation with new config options
Browse files Browse the repository at this point in the history
  • Loading branch information
@yasunariw
yasunariw committed Dec 19, 2020
1 parent 49e8ecc commit 44d32de
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 74 deletions.
73 changes: 30 additions & 43 deletions documentation/config_docs.md
View file
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.

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,38 +70,28 @@ 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",
"rules": [
{
"allow": [
"backend"
],
"ignore": [],
"allow": ["backend"],
"channel": "backend"
},
{
"allow": [
"aa"
],
"ignore": [],
"allow": ["aa"],
"channel": "aa-git"
},
{
"allow": [
"siren"
],
"ignore": [],
"allow": ["siren"],
"channel": "siren"
},
{
"allow": [],
"ignore": [
"backend",
"aa",
Expand All @@ -113,57 +105,52 @@ 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 | None |
| `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. 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.

| 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` | whitelist of label values; if not provided, the rule is vacuously satisfied | Yes | - |
| `ignore` | blacklist of label values; any labels matching will not match the rule | 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",
"rules": [
{
"allow": [
"backend/api"
],
"ignore": [],
"allow": ["backend/api"],
"channel": "aa"
},
{
"allow": [
"backend/megaindex",
"backend/ahrefskit"
],
"ignore": [],
"channel": "backend"
},
{
"allow": [],
"ignore": [],
"channel": "all-push-events"
}
]
},
```


### 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` | whitelist of file prefixes that match the rule | Yes | - |
| `ignore` | blacklist of file prefixes that do not match the rule | Yes | - |
| `channel` | channel to use as webhook if the rule is matched | No | - |
41 changes: 10 additions & 31 deletions documentation/secret_docs.md
View file
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_webhook_secret` | 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.

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

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

0 comments on commit 44d32de

Please sign in to comment.