Matrix bot using a GitHub webhook to get news on Specs Change Submissions (SCS) and send notices about a state change to Matrix rooms.
Clone or download
Pull request Compare This branch is 2 commits ahead, 7 commits behind Informo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Specs bot

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.

Building it also requires gb:

go get

Once everything is setup correctly, clone this repository, retrieve the project's dependencies and build it:

git clone
cd specs-bot
gb vendor restore
gb build

The bot's binary should now be available as bin/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 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)

Example: Informo

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:


Example: 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:


What is Informo?

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.