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 instauctions for self-hosting

Step 1: Register a new GitHub App

The first step is to register a new GitHub App on the GitHub web site.

App settings

The GitHub App name, description, and homepage URL are irrelevant, though I suggest pointing the homepage at the dashboard page.

The user authorization callback URL should be at <DASHBOARD URL>/auth/github/callback.

Leave the setup URL blank.

The webhook URL should be at <DASHBOARD URL>/webhook/github.

The webhook secret should be a randomly generated string. The mix phx.gen.secret command will work awesomely for this. Keep this handy to specify the same value in the bors configuration (you can also edit this value later if you need to).

Required GitHub App permissions

Permission summary
Click here to view a screenshot

For each of these sections, set the following overall section permissions and check the following webhook event checkboxes. Explanations for why bors-ng needs each of these permissions are below.

Permission explanations

Repository metadata will be read-only. Must be set to receive Repository events to automatically remove entries from our database when a repo is deleted.

Commit statuses must be set to Read & write to report a testing status (this is the older version). Also must get Status events to integrate with CI systems that report their status via GitHub.

Issues must be set to Read & write because pull requests are issues. Issue comment events must be enabled to get the “bors r+” comments. If Issues is set to Read-only, repos will end up with pull requests that are marked as simultaneously merged and opened.

Pull requests must be set to Read & write to be able to post pull request comments. Also, must receive Pull request events to be able to keep the dashboard working, and must get Pull request review and Pull request review comment events to get those kinds of comments.

Repository contents must be set to Read & write to be able to create merge commits.

Checks must be set to Read & write to report a testing status (this is the newer version). Also must get Check run events to integrate with CI systems that report their status via GitHub.

Organization members must be set to Read only to synchronize repository contributors and bors reviewers.

After you click the “Create” button

GitHub will send a “ping” notification to your webhook endpoint. Since bors is not actually running yet, that will fail. This is expected.

You’ll need the following values from your GitHub App for configuring bors-ng:

Internal app?

GitHub Apps can be set as “Internal” or “External”. When the App is set to be internal, then whichever organization/user it belongs to will be the only one allowed to install it.

This setting can be chosen while first creating the app, or it can be changed afterward at one of these URLs (the switch is on the bottom of the page):

If an “External” app is installed on any external repositories, then the “Make Internal” button will be grayed out.

Step 2: Set up the server

bors-ng is written in the Elixir programming language, and it uses PostgreSQL as the backend database. Whatever machine you plan to run it on needs to have both of those installed.

bors-ng is built on the Phoenix web framework, and they have docs on how to deploy phoenix apps already. Where you deploy will determine what the dashboard URL will be, which is needed in the previous steps, so this decision needs to be made before you can set up the GitHub App.

You’ll need to edit the configuration with a few bors-specific variables.

Deploying on Heroku (and other 12-factor-style systems)

The config file in the repository is already set up to pull the needed information from the environment, so you can configure bors by setting the right env variables and deploy the app from this repository into Heroku:

Run these commands to deploy on Heroku:

Note: The GITHUB_INTEGRATION_ID is now called the App ID on GitHub.

$ heroku create --buildpack "https://github.com/HashNuke/heroku-buildpack-elixir.git" bors-app
$ heroku buildpacks:add https://github.com/gjaldon/heroku-buildpack-phoenix-static.git
$ heroku addons:create heroku-postgresql:hobby-dev
$ heroku config:set \
    MIX_ENV=prod \
    POOL_SIZE=18 \
    PUBLIC_HOST=bors-app.herokuapp.com \
    ALLOW_PRIVATE_REPOS=true \
    COMMAND_TRIGGER=bors \
    SECRET_KEY_BASE=<SECRET1> \
    GITHUB_CLIENT_ID=<OAUTH_CLIENT_ID> \
    GITHUB_CLIENT_SECRET=<OAUTH_CLIENT_SECRET> \
    GITHUB_INTEGRATION_ID=<ISS> \
    GITHUB_INTEGRATION_PEM=`base64 -w0 priv.pem` \
    GITHUB_WEBHOOK_SECRET=<SECRET2> \
    [BORS_LOG_LEVEL=<debug|info|warn|...>]
$ git push heroku master
$ heroku run POOL_SIZE=1 mix ecto.migrate

WARNING: bors-ng stores some short-term state inside the web dyno (it uses a sleeping process to implement delays, specifically). It can recover the information after restarting, but it will not work correctly with Heroku’s replication system. If you need more throughput than one dyno can provide, you should deploy using a system that allows Erlang clustering to work.

Deploying using Docker (and compatible container orchestration systems)

Pre-built Docker images are available at Docker Hub for the current master (as bors-ng:latest).

The Dockerfile in the project root can be used to build the image yourself. It relies on multi-stage builds as introduced in Docker 17.05, to generate a slim image without the Erlang, Elixir and NodeJS development tools.

Most of the important configuration options should be set at runtime using environment variables, not unlike the Heroku instructions. All the same recommendations apply, with some extra notes:

Deploying on your own cluster

Your configuration can be done by modifying config/prod.secret.exs.

Optional step 3: make yourself an admin

bors-ng offers a number of special functions for “administrator” users, including diagnostics and the ability to open a repo dashboard without being a reviewer.

However, there’s no UI for adding admins; you’ll have to go into Postgres yourself to do it. There’s two ways to do that:

You can do it from the iex prompt, like this:

shell$ iex -S mix # or `heroku run bash -c "POOL_SIZE=1 iex -S mix"`
iex> me = BorsNG.Database.Repo.get_by! BorsNG.Database.User, login: "<your login>"
iex> BorsNG.Database.Repo.update! BorsNG.Database.User.changeset(me, %{is_admin: true})

You can do it from a PostgreSQL prompt like this:

postgres=# \c bors_dev -- or bors_prod
bors_dev=# update users set is_admin = true where login = '<your login>';

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

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.