Getting started

You need a Ruby project with RSpec or Minitest, a CI provider, and about ten minutes.

1. Create a suite and get an API key

Sign in at app.selective.ci and create a suite for your repository. Selective gives you an API key for the suite. One suite maps to one test command in one repository; a repo with both RSpec and Minitest is two suites.

2. Add the gem

bundle add selective-ruby-rspec      # RSpec
bundle add selective-ruby-minitest   # Minitest

The gem bundles a native transport binary for x86_64-linux, aarch64-linux, x86_64-darwin and arm64-darwin. If CI reports Unable to find executable for <platform>, the platform is missing from your Gemfile.lock:

bundle lock --add-platform x86_64-linux

Installing the gem also builds a small native extension used to record test maps. That needs make and a C compiler, as any gem with a native extension does. If it can’t build, installation still succeeds and everything works except recording; see Test selection.

3. Add the API key to CI

Store the key as a secret named SELECTIVE_API_KEY in your CI provider. Never commit it.

4. Configure your CI provider

On GitHub Actions and CircleCI there is a small setup step. On Semaphore, Buildkite and RWX the secret is all you need.

• GitHub Actions
• CircleCI
• Semaphore
• Buildkite
• RWX
• Any other provider

5. Swap the test command

bundle exec rspec
bundle exec selective rspec

bundle exec rake test
bundle exec selective minitest

Your existing framework flags still work. bundle exec selective rspec spec/models --tag focus runs exactly what bundle exec rspec spec/models --tag focus would have, through Selective.

6. Run it

Push a commit. Each CI node connects to Selective, the run appears at app.selective.ci, and results stream in as tests finish. From a terminal in the repo:

selective tail

streams the same results for the current commit. See the CLI.

7. Run in parallel

Selective distributes tests across every node that connects with the same run identifiers, so parallelism is just running the same command on more nodes. Each node needs a stable identity across retries of the same build; on the detected providers that comes from the parallel job index automatically. On GitHub Actions the setup action takes it as runner-id.

8. Turn on test selection

Selection is off for a new suite. Selective learns which files each test executes from a recording run, so the recommended path is:

1. Add a daily scheduled run with SELECTIVE_TEST_MAP_RECORD=1 (keeping the map fresh), and set the suite to record. The first run records a map.
2. Switch to shadow. Selective computes the selection for every run and shows what it would have skipped, but still runs everything.
3. When the shadow reports look right, switch to select.

Shadow mode never holds a build: every test runs as usual, and the selection is worked out in the background. An optional warm-up step has selection ready before your test nodes start.

For live mode, install the Selective GitHub App on the repository and ask support to turn on semantic selection for your organization.

The full setup checklist covers every step, including what each provider needs for the daily recording job and the warm-up, and how to check each one worked. Details in How test selection works.