Skip to content

Bors merge bot

Jump to bottom
Andrew Couch edited this page Apr 10, 2018 · 10 revisions

Overview

To enable true continuous integration, we merge pull requests using a bot. Craig is that bot, an instance of bors-ng. He runs the build for approved PRs as if they were merged, and merges them only after the build passes. This is in contrast to the default GitHub workflow, which tests the PR itself, but doesn't test the merge to master until after merging.

Workflow

The normal workflow is pretty simple: once a PR has received an LGTM, add a comment saying bors r+. (See the Bors docs for a full list of commands).

Craig will take the approved PR (along with any other PRs approved at around the same time), merge them to master (or whatever the PR's target branch is), and push that as the branch named staging. This will trigger the TeamCity build for the merge candidate. If everything goes right and the build passes, Craig will fast-forward master to staging, and each of the PRs will be marked as merged.

If the combined changes end up breaking the build, you've found a situation where Craig saved us from "merge skew". Craig will then proceed to bisect the PRs to identify which one(s) can merge safely and which one(s) caused the problem. If your PR merges successfully at this stage, great! Otherwise, Craig will comment with details about the failed build. At that point you'll need to investigate and resolve the issue. If the underlying cause was a flaky test, you can just try bors r+ again (in addition to reporting the flake to the appropriate channels). If the failure was due to merge skew, you'll need to resolve the merge.

If you'd like Craig to build your PR without merging to master, you can say bors try.

FAQ

  • How is Bors configured? There's not many configuration options, but what there is can be found in bors.toml in the root of the repository.
  • When does Bors process the config file? At the time commands are issued, Bors looks for a bors.toml in the PR to be merged. This means if you haven't changed it, the config file from your PR's target branch is used.
  • Is there a log of what Bors does somewhere? Yep! For this repo, you can find it here.
  • How do I add Craig to other repos? Craig is already listening to all the repos under @cockroachdb. There are two steps to making Craig respond to commands somewhere else: part one is to add a bors.toml config file to the repo that tells Bors what CI status to wait on, and part two is adding everyone as reviewers on the repo's settings page on the Bors dashboard.
  • Craig told me "Permission denied"! You are not currently a reviewer, so just ask someone who is to add you to the list of reviewers on the settings page.
  • My question isn't answered here! Ask on the mailing list, or if you're an internal Cockroach dev, on Slack in the channel #bors.

Known Limitations

  • #163: currently Bors will not automatically close issues if they are listed only in commit messages, however they will be closed if they appear in the PR description.
  • #165: user management is currently relatively manual. If you need permissions to act as a reviewer, ask someone to add you.

Restarting Bors

  • Log into the Google cloud dashboard.
  • Navigate to Compute > Compute Engine > VM Instances and find Bors.
  • Click "Stop", wait for the instance to stop, then click "Start".
  • Copy the new IP address of the instance.
  • Navigate to Storage > SQL and find bors-db.
  • Under Authorization, update the whitelist with the new IP address.
  • DO NOT change the DNS settings. The DNS is pointing to the LB, which is pointing to the instance group, which gets the updated IP address automatically.
  • Visit the dashboard and try a bors ping to make sure Bors is back up.

More information

Clone this wiki locally