Pipeline setup

Every CI system that can run a shell step can run Bellwether. The shape is always the same: select, then run your own command against the selection.

The two lines

A hosted-runner workflow, as an example:

- run: bellwether select --base ${{ github.event.pull_request.base.sha }}
- run: bundle exec rspec $(cat .bellwether/selected)

A self-hosted build farm with a plain shell step:

bellwether select --base "$TARGET_BRANCH_SHA"
pytest $(cat .bellwether/selected)

Set BELLWETHER_TOKEN as a secret in your CI. The token is scoped to one repository and can only write selections and results.

The nightly full run

Add one scheduled job that runs the whole suite with the recorder attached:

bellwether record --nightly -- bundle exec rspec

This refreshes the map and compares the night’s results with the day’s selections. If a test fails at night that a selection skipped during the day, the report names the stale map entry and the next selection runs that test.

Parallel machines

To split the selection across machines, pass the shard index on each one:

bellwether select --base main --shard $CI_NODE_INDEX/$CI_NODE_TOTAL

Each machine reads its own share, balanced by recorded duration. See shard balancing for how the split is made.

Runners behind a firewall

The CLI talks to one host, api.bellwether.example, over HTTPS on port 443. If your runners cannot reach it, the Enterprise plan runs the map store inside your network.