What is bors?

Bors is a merge bot that makes sure our dev branch is evergreen. It does so by running all the tests (including integration tests!) before the merge, and - only if they pass! - pushing the exact same commit that was tested to the target branch.

To make this efficient, bors:

• implements a build queue,
• tries to build and merge all the queued PRs at once, in so called "batches",
• bisects the batch into two smaller ones should its build fail.

This approach prevents semantic conflicts and in fact - because only bors can merge to dev - allows us to not even have a dev branch build.

How do I use it?

1. You open a PR, and get a review approval,
2. you write bors r+ in a comment,
3. bors merges your PR to the target branch after it passes a full build,
4. (optional) you open the dashboard and see your build queued/running,
5. (optional) bors writes a comment in your PR if the build failed - you fix it and go to (3.).

Other commands:

• bors try runs integration tests for the PR without scheduling a merge,
• bors delegate+ enables non-maintainer PR authors to bors r+ and bors try,
• bors r- cancels a scheduled merge,
• bors ping makes sure the bot is up.

How does it work?

For details, see:

• How it works section in bors-ng readme,
• bors.tech,
• bors docs,
• bors reference,
• bors forum.

FAQ

The PR build passed, the reviewer approved, I can't click "Merge" in GitHub. Why?

Because only bors can merge to dev. Instead of clicking "Merge", you ask bors to do that by saying bors r+.

I said bors r+, nothing happend. Why?

Possible reasons:

1. You didn't refresh the PR page. The 'bors mentioned this PR in a commit' notification only shows after a refresh. Or I'm impatient.
2. Your build has been queued b/c another one is being run ATM. See the dashboard.

I added a commit after a merge build started, bors said "build cancelled". Why?

Because if it's to be merged, it needs to be tested :) Just request bors r+ again.

I canceled a merge using bors r- or by pushing more changes, but the CI build was not cancelled. Why?

Bors has no means for cancelling a build - it merely pushes branches and observes the CI statuses in GitHub. Make sure to cancel any orphan builds so that others don't wait needlessly. Thanks! :)

I said bors retry and it acted funny. Why?

retry support is quite primitive, in my experience. Bors works best when you tell it what to do exactly :)

Where does bors live?

In the cloud. At least the (public) instance we use.

Why is it called bors?

See here.