Bors

Home of a 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.
--client-id	OAUTH_CLIENT_ID		GitHub OAuth client ID for rollup UI (optional).
--client-secret	OAUTH_CLIENT_SECRET		GitHub OAuth client secret for rollup UI (optional).
--db	DATABASE_URL		Database connection string. Only PostgreSQL is supported.
--cmd-prefix	CMD_PREFIX	@bors	Prefix used to invoke bors commands in PR comments.
--web_url	WEB_URL	http://localhost:8080	Web URL where the bot’s website is deployed (optional).
--permissions	PERMISSIONS	Rust Team API URL	Either a URL to the team v1 API or a path to a directory containing JSON files with try/review permissions (optional).

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.

OAuth app

If you want to create rollups, you will need to create a GitHub OAuth app configured like so:

1. In the developer settings, go to “OAuth Apps” and create a new application.
2. Set the Authorization callback URL to <http address of bors>/oauth/callback.
3. Note the generated Client ID and Client secret, and pass them through the CLI flags or via your environment configuration.

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.

We would like to thank all contributors who contributed to the creation of bors. Notably, we are very grateful to Võ Hoàng Long, who implemented a lot of the base functionality of the bot, and Sakibul Islam, who implemented the merge queue and rollups as part of his GSoC 2025 project.

License

Bors is dual-licensed under MIT and Apache 2.0.