Documentation

Bisect finds the commit that broke your code. Install the GitHub App on your repo, mention @bisect-sh in any issue, and get the culprit commit posted back automatically. You can also use the CLI for local workflows.

GitHub App

The Bisect GitHub App is the fastest way to find regressions. Install it on your repository, then trigger a bisect directly from a GitHub issue or comment—no CLI needed.

Install

Visit github.com/apps/bisect-sh and install the app on your organization or personal repos. Grant access to the repositories you want to bisect.

Trigger Format

Mention @bisect-sh in an issue body or comment with CLI-style flags:

@bisect-sh --good <commit> --bad <commit> --test-cmd "<command>"

The --good and --bad flags are required. Everything else is optional. Commits can be SHA hashes (7–40 hex chars), HEAD, or full GitHub commit URLs.

Legacy key-value format

Bisect also supports a plain key-value format in the issue body:

good: abc1234
bad: HEAD
test: npm test

Supported Flags

How It Works

1. You mention @bisect-sh in a GitHub issue or comment with the required flags. This can be a new issue or a comment on an existing one.
2. Bisect acknowledges by posting a comment with a parameter table confirming the job ID, good/bad commits, and test command.
3. A cloud VM spins up, clones your repo, and runs git bisect across the commit range using your test command.
4. Results are posted back as a comment on the issue with the first bad commit (linked to the GitHub diff), a summary table, and expandable test output.
5. The issue is labeled and closed. Bisect adds a bisect:found label (or bisect:failed) and closes the issue automatically.

GitHub Examples

Full example — all flags

This is a real-world example from a PyTorch repo. It uses every flag—a specific branch, a heavy-compute instance, a setup script, and a targeted test command:

@bisect-sh --branch main --instance c5.4xlarge \
  --good 5369b935 --bad HEAD \
  --setup-cmd "./setup.sh" \
  --test-cmd "python test/dynamo/test_misc.py -k test_shape_unpack"

--branch main checks out the main branch before bisecting. --instance c5.4xlarge uses a 16-vCPU compute-optimized instance for heavy compilation. --setup-cmd runs before each bisect step (install deps, compile, etc.). --test-cmd is the pass/fail test—exit 0 means the commit is good.

Basic — find which commit broke tests

@bisect-sh --good v2.3.0 --bad HEAD --test-cmd "npm test"

With setup command and filtered tests

Use --setup-cmd to install dependencies before each bisect step:

@bisect-sh --good abc1234 --bad HEAD \
  --setup-cmd "npm install" \
  --test-cmd "npm test -- --filter=auth"

Heavy workload with timeout

Use a larger instance for CPU-intensive builds. Set --timeout when bisecting long commit ranges:

@bisect-sh --good c8a9b34 --bad HEAD \
  --test-cmd "cargo test" \
  --instance c5.xlarge --timeout 120

Subdirectory project

@bisect-sh --good v1.0.0 --bad HEAD \
  --test-cmd "cd packages/api && bun test"

Branch + setup + custom instance

Combine multiple flags for complex projects that need a specific branch and build step:

@bisect-sh --branch develop --instance t3.large \
  --good abc1234 --bad HEAD \
  --setup-cmd "pip install -e ." \
  --test-cmd "pytest tests/ -x"

Account Linking

When you install the GitHub App, your GitHub username is automatically linked to your Bisect account. This means bisect jobs you trigger from GitHub issues use your credit balance and appear in your job history.

If someone triggers a bisect without a linked Bisect account, a shared project account is created automatically per GitHub App installation with a free credit balance.

CLI Reference

The CLI is an alternative to the GitHub App for local workflows. Install it, authenticate, and run bisects from your terminal.

Install

curl -fsSL https://bisect.sh/install.sh | bash

Login

bisect login

Run a bisect

bisect run --good v1.0.0 --bad HEAD --test-cmd "make test"

bisect <test-script> <good-commit> <bad-commit>

Full Help Output

Bisect CLI

Usage: bisect-linux-amd64 [OPTIONS] [COMMAND]

Commands:
  login  Login via browser
  run    Run a bisect job
  help   Print this message or the help of the given subcommand(s)

Options:
      --verbose  Enable debug output
  -h, --help     Print help
  -V, --version  Print version

CLI Examples

Repo URL flow

Pass a public repo URL and bisect runs entirely on the VM:

bisect run --repo https://github.com/user/repo.git \
  --good v1.0.0 --bad HEAD --test-cmd "make test"

Workspace flow

Run from inside a local repo. The CLI syncs your workspace to the cloud:

cd ~/my-project
bisect run --good abc1234 --bad HEAD --test-cmd "./test.sh"

Custom instance

bisect run --good v2.0 --bad HEAD \
  --test-cmd "cargo test" --instance t3.large --timeout 60