Setting up bors

Bors-NG does not replace CI tools like Travis CI; it’s just a frontend that implements a particular workflow on top of it. So the first step of setting up bors is setting something up to automatically run your tests. It should be able to run the contents of a particular branch and report its results using a GitHub Status notification (the little , , or × next to a commit in the commits list).Newer CI systems, like Travis and AppVeyor, will do this by default. Jenkins and BuildBot have plugins for it.

Your CI system should build the “staging” and “trying” branches, but should not build a branch called “staging.tmp”. If your CI system is misconfigured to do this, bors should notify you. For example, add this to your .travis.yml or appveyor.yml file:

branches:
  only:
    # This is where pull requests from "bors r+" are built.
    - staging
    # This is where pull requests from "bors try" are built.
    - trying
    # Uncomment this to enable building pull requests.
    #- master

Once you have a Continuous Integration service running, connect bors-ng to your repo from within GitHub.

The final step is to create a bors.toml file in your repo. This will specify what CI systems Bors-NG should use, along with other metadata like timeouts. The status key specifies which GitHub Statuses it uses to determine a successful or failed build. For example, this will work for a repo with Travis CI and AppVeyor:

status = [
  "continuous-integration/travis-ci/push",
  "continuous-integration/appveyor/branch"
]
# Uncomment this to use a two hour timeout.
# The default is one hour.
#timeout_sec = 7200

Once that’s there, bors r+ will work. Note that bors reads bors.toml from the pull requests it’s merging, not the one in master, so changes to the file get checked before they land.

Reviewing pull requests

Once you’ve set it up, instead of clicking the green “Merge Button”, leave a comment like this on the pull request:

bors r+

The pull request, as well as any other pull requests that are reviewed around the same time, will be merged into a branch called “staging”. Your CI tool will test it in there, and report the result back where Bors-NG can see it. If that result is “OK”, master gets fast-forwarded to reach it.

The status can be seen in the Dashboard page, which also makes a good one-stop-shop to see pull requests that are waiting for review.

There’s also:

bors try

When this is run, your branch and master get merged into “trying”, and bors will report the results just like the “staging” would (you probably want to make sure your CI system handles staging and trying the same). Only reviewers can push to this, since the backend CI system may not be well-isolated.

Adding reviewers

If you click your nickname on the Dashboard page, there’s a button to get a list of Repositories. Click there, then click the repository you want to look at.

There’s two tabs: a Pull requests tab and a Settings tab. Click the settings tab.

In there is a list of currently set up reviewers. Type the GitHub login name of the user you want to add, into the text field next to the “Add” button, then click it.

Delegating reviews

In addition to adding reviewers who can approve any PR in the repo, you can “delegate” permission to approve a single PR to anyone else. It works like this:

  • @some-user: bors r+
  • @bors[bot]: Permission denied
  • @some-reviewer: bors delegate=some-user
  • @bors[bot]: some-user now has permission to review this pull request.
  • @some-user: bors r+
  • @bors[bot]: Added to queue

If some-user happens to be the pull request author, you can also use the shorthand delegate+ command.

More info

You can find more info in the reference manual.

If it doesn’t work

It might be one of these common problems:

You can also get help on our forum. We won’t chew you out if it turns out to be one of those problems after all.