Bors

Home of a (WIP) rewrite of the homu bors implementation in Rust.

There are a few documents that should help with understanding the bot:

• Design of the bot.
• Development guide.

If you want to help testing the bot, please ask around on the #t-infra stream on Rust Zulip.

The production instance of the bot is deployed at https://bors-prod.rust-lang.net. You can find its help page with the list of supported commands here.

Configuration

There are several parameters that can be configured when launching the bot. Parameters without a default value are required.

CLI flag	Environment var.	Default	Description
--app-id	APP_ID		GitHub app ID of the bors bot.
--private-key	PRIVATE_KEY		Private key of the GitHub app.
--webhook-secret	WEBHOOK_SECRET		Key used to authenticate GitHub webhooks.
--db	DATABASE_URL		Database connection string. Only PostgreSQL is supported.
--cmd-prefix	CMD_PREFIX	@bors	Prefix used to invoke bors commands in PR comments.

Special branches

The bot uses the following branch names for its operations.

Try builds

• automation/bors/try-merge
  • Used to perform merges of a pull request commit with a parent commit.
  • Should not be configured for any CI workflows!
• automation/bors/try
  • This branch should be configured for CI workflows corresponding to try runs.

Auto builds

• automation/bors/auto-merge
  • Used to merge PR with the latest base branch commit.
  • Should not be configured for any CI workflows!
• automation/bors/auto
  • This branch should be configured for CI workflows that need to run before merging to the base branch.

The merge and non-merge branches are needed because we cannot set branches to parent and merge them with a PR commit atomically using the GitHub API.

GitHub app

If you want to attach bors to a GitHub app, you should point its webhooks at <http address of bors>/github.

How to add a repository to bors

Here is a guide on how to add a repository so that this bot can be used on it:

1. Add a file named rust-bors.toml to the root of the main branch of the repository. The configuration struct that describes the file can be found in src/config.rs. Here is an example configuration file.
2. Install the GitHub app corresponding to this bot to the corresponding repository. You can use the https://github.com/settings/apps/<app-name>/installations link.
3. Enable the corresponding permissions and webhook events for the GH app (see this).
4. Configure CI workflows on push to:
   • automation/bors/try branch (for try builds)
   • automation/bors/auto branch (for auto builds)
5. Give the bot permissions to push to automation/bors/try, automation/bors/try-merge, automation/bors/auto, and automation/bors/auto-merge.

Contributing

We are happy to receive contributions to bors! You can check out our list of good first issues.

Note that sometimes the issues can get stale or they might not contain enough information that you would need to implement a feature or fix a bug. If you would like to work on something non-trivial, it would be great to open a topic on our Zulip channel so that we can discuss it.

License

Bors is dual-licensed under MIT and Apache 2.0.