The specs bot is a Matrix bot that shares state updates of a specifications proposal to the configured Matrix rooms. While initially designed to shout about updates to the Informo open specs, we made it compatible to most specifications projects using GitHub issues or pull requests to track proposals and labels to track a proposal's state.
It works by setting up a GitHub webhook listening on pull requests and issues events. Each time it receives a matching payload, and if the event was triggered by a change in the PR/issue's list of labels, it generates an update message by selecting a configured string matching the update and processing it (along with some information specific to the PR/issue) through the configured template. It then sends the message as a notice to the configured Matrix rooms.
You can install the bot by building it or using one of the binaries available in the project's releases.
This project is written in Go, therefore building it requires a Go development environment. It requires Go 1.11+.
In order to build the bot, you should first clone the repository:
git clone https://github.com/Informo/specs-bot
cd specs-bot
go build
The bot's binary should now be available as ./specs-bot. You can run it as it is, or with the --debug flag to make it print debug logs, which explain the whole path of a payload's content through the different workflows.
The bot currently only support GitHub webhooks and expects them to be send with the application/json content type.
The bot needs two configuration files to do its job.
The first configuration file is the general one, which will allow defining the settings to connect to Matrix, set the webhook up, and generate Matrix notices. All of its configuration keys are documented in the sample file. The path to the configuration file can be provided as follows:
/path/to/specs-bot --config /path/to/config.yaml
If no value for the --config flag is provided, it will default to ./config.yaml.
The second configuration file contains the strings to use when generating the notice message, in the JSON format. An example file is available here. This file is split in three sections: typo and behaviour contains strings that match states from the Informo SCSP, respectively for typo and behavioural changes. The global section contains strings that are either common between the two types, or not related to the Informo SCSP. Therefore, an instance of the bot set up to follow proposals to a specifications project that doesn't follow Informo's SCSP must have all of its strings defined in the global section.
The file path can be configured in the general configuration file (config.yaml)
The strings to use in Informo's use case are defined in the strings.json file located in this repository.
In this example, and using the pattern in the sample configuration file, doing this in GitHub's interface:
Triggers the sending of this notice to Matrix:
Let's consider using the bot to follow updates to proposals to the Matrix specifications. The JSON strings file should then look like:
{
"global": {
"proposal-in-review": "is currently in review",
"proposal-passed-review": "passed review as worth implementing and then being added to the spec",
"proposal-ready-for-review": "is now ready and waiting for review by the core team and community",
[...]
}
}In this example, and using the pattern in the sample configuration file, doing this in GitHub's interface:
Triggers the sending of this notice to Matrix:
This release includes a python3 script called fill-db.py in the scripts/fill-db directory. Its purpose is to initially seed a database with proposals and their labels. The reason for it is that specs-bot only tracks changes between labels, and thus if a proposal is already halfway through completion when specs-bot is activated, it will end up outputting multiple events as it finds out about all the labels that were already on the issue prior to specs-bot coming online.
The script fixes this issue by initially downloading all information about all issues/PRs (or other those with certain labels) and their label information, so that specs-bot can be up-to-date about the repo's proposals as soon as it comes online.
To use, make sure you have python3 and pip installed, then install the script's python requirements:
pip3 install -r scripts/fill-db/requirements.txt
Then, open scripts/fill-db/fill-db.py and enter in your repository information (ex: "Informo/specs"), your Github personal access token, your sqlite3 DB location (ex: "./specs-bot.db") and the labels you'd like to filter issues/PRs by as a list of strings (or leave as an empty list to download all issues/PRs). Once done, simply run the script from this repo's root directory:
python3 scripts/fill-db/fill-db.py
Your sqlite3 DB file should now be seeded with all proposals and their label information. You can now start specs-bot and be confident it'll show changes as intended.
The bot can be run inside a Docker container. The image can be found on the Docker Hub. It exposes the port 8080, on which the bot is expected to listen.
Building the image from scratch can be done with:
docker build -t informo/specs-bot -f docker/Dockerfile .A configuration file and a strings file are needed. Examples can be found in the Docker configuration directory.
Once both files are ready, run the image with the configuration file and mount the configuration directory:
docker run --name specs-bot -p 8080:8080 -v /path/to/config/directory:/etc/specs-bot specs-botBy running the image with the configuration directory mounted, the bot will initialise a SQLite database in the mounted directory. Therefore, run the image once then kill the container. The SQLite database will have been created in the directory where the configuration lives.
Run the script on that database (by setting DB_PATH to the right value), then you can start the bot again, with the same directory mounted as it was during the initial run, and it should start using your updated database.
Informo is an open project using decentralisation and federation to fight online censorship of the press. Read more about it here, and join the discussion online on Matrix or IRC.