Setting up bors

Bors-NG does not replace CI tools like Travis CI or Github Actions; 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.

The general steps to setup bors-ng are:

Detailed instructions for various CI systems

Setting up Travis

For travis, the configuration to limit to particular branches should look something like this:

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 travis running, connect bors-ng to your repo from within GitHub.

Next, create a bors.toml. It should look something like this:

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.

Configuring CircleCI

CircleCI configuration should look something like this:

workflows:
  build-deploy:
    jobs:
      - test:
          # run full test cycle for 'merge' or 'try'
          filters:
            branches:
              only: 
                - staging
                - trying
      - publish:
          requires:
            - test
          # only publish site changes on 'merge'
          filters:
            branches:
              only: staging

Next, install the bors application as described above.

Next, create a bors.toml file which specifies the job names or workflow name to require:

#CircleCI using GitHub Status
status = [
  "ci/circleci: jobname"
  
]

#CircleCI using GitHub Checks
status = [
  "workflow-name" 
]

Configuring Github Actions

First, configure a workflow that builds Rust that is configured to run on pushs to the main, staging, and trying branches. As an example, for a Rust project, you might have a .github/workflows/rust.yml file like this:

name: Rust

on:
  push:
    branches: [main, staging, trying]
  pull_request:
    branches: [main]

env:
  CARGO_TERM_COLOR: always

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
      - name: Build
        run: cargo build --verbose
      - name: Run tests
        run: cargo test --verbose

Next, install the bors application as described above.

Next, create a bors.toml file which specifies the status names. To figure out what name to use, use the name of the job (Build, in our example above). You can find that by looking at the “status” marks on your PR. It should say something like Rust / Build (...), in which case you want the Build (the Rust part comes from the name of the workflow, and that is not what you want).

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+

Equivalently, you can comment the following:

bors merge

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.