Buildkite Preflight

When to Run Preflight

• After completing the requested implementation and local tests pass, use preflight to run the whole test suite on CI
• Before a long unsupervised session ends if you've made multiple changes
• After fixing a failure from a previous preflight run
• Not for trivial changes like typos, comment-only edits, or single-line config tweaks unless the user asks
• When the user asks to verify changes work in CI

Before Running

• Prefer an explicit pipeline in

  {org}/{pipeline}

  form
• Ensure

  bk auth

  is pointed at the right Buildkite organization when the pipeline slug relies on local config
• Requires a git repository with at least one commit and push access to

  origin

• Requires

  read_builds

  ,

  write_builds

  , and

  read_pipelines

  scopes; and

  read_suites

  for Test Engine results.
• Run preflight in a subagent

Running Preflight

# Human-readable output that works well in agent shells
bk preflight --pipeline my-org/my-pipeline --watch --text

# Start a run and return as soon as the build enters the failing state
bk preflight --pipeline my-org/my-pipeline --watch

# Wait for a terminal build state instead of fast-failing
bk preflight --pipeline my-org/my-pipeline --watch --exit-on=build-terminal

# Start the build and exit immediately
bk preflight --pipeline my-org/my-pipeline --no-watch

# Leave the remote preflight branch and build running on early exit
bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup

# Wait for 30s after build completion for Test Engine summaries
bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 30s

How It Works

1. Snapshot - Captures staged, unstaged, and untracked files using a temporary git index, without modifying the real index or working tree.
2. Commit - Creates a distinct preflight commit on top of

   HEAD

   , even when the tree is clean, so the run has its own commit status context.
3. Push - Pushes that commit to

   refs/heads/bk/preflight/<uuid>

   on

   origin

   .
4. Create Build - Calls the Buildkite Create Build API and sets

   PREFLIGHT=true

   ,

   PREFLIGHT_SOURCE_COMMIT

   , and

   PREFLIGHT_SOURCE_BRANCH

   when available.
5. Monitor - Watches the build and emits operation events, build status updates, job failures, retry-passed jobs, and a final summary.
6. Cleanup - Deletes the remote preflight branch when the run finishes unless

   --no-cleanup

   is set. With the default

   --exit-on=build-failing

   , early exit also cancels the remote build unless

   --no-cleanup

   is set.

Reading the Result

• The default exit policy is

  build-failing

  , so the preflight command exits as soon as the build enters the

  failing

  state.

• --exit-on=build-terminal

  waits for a terminal build state (passed, failed, canceled).

• --await-test-results

  waits after build completion for Test Engine rollups when test runs exist.
• Final job summaries cover hard-failed script jobs and exclude non-script, broken, and soft-failed jobs
• Failed job output includes the job id. Use

  bk job log -b <build-number> -p <org>/<pipeline> <job-id>

  to inspect logs.
• When analytics are available, the final summary shows per-suite passed/failed/skipped counts and up to 10 failed tests.
• Test failures include the test name and location; reproduce the failure locally and fix it.
• If a failure is flaky/unrelated to your changes, note it to the user rather than trying to fix it.

Just the failed jobs from the summary:

bk preflight --pipeline my-org/my-pipeline --watch --json \
  | jq -nrc --unbuffered 'inputs | select(.type == "build_summary") | .failed_jobs'

Just the failed tests from the summary:

bk preflight --pipeline my-org/my-pipeline --watch --json \
  | jq -nrc --unbuffered 'inputs | select(.type == "build_summary") | .tests.failures'

Output Modes

• Use

  --text

  for plain text logs that are easy to read in tool output
• Use

  --json

  when you need structured event data
• If neither flag is set,

  bk

  uses the interactive TTY UI when stdout is a terminal and plain text otherwise

Running a Preflight Build

Basic usage

# Run preflight and watch until completion
bk preflight --pipeline my-org/my-pipeline --watch

# Run without watching (starts the build and exits)
bk preflight --pipeline my-org/my-pipeline --no-watch

# Skip confirmation prompts (useful in scripts)
bk preflight --pipeline my-org/my-pipeline --watch --yes

# Keep the remote preflight branch after the build finishes
bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup

# Use plain text output in non-interactive environments
bk preflight --pipeline my-org/my-pipeline --watch --text

# Use JSONL output when another tool needs structured events
bk preflight --pipeline my-org/my-pipeline --watch --json

# Wait for 10s for Test Engine results after build completion
bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 10s

Pipeline resolution

--pipeline

{org slug}/{pipeline slug}

# With org prefix (explicit)
bk preflight --pipeline my-org/my-pipeline --watch

# Pipeline slug only (org resolved from bk config)
bk preflight --pipeline my-pipeline --watch

Flags

--pipeline

-p

{slug}

{org}/{slug}

--[no-]watch

--exit-on

build-failing

build-failing

build-terminal

--interval

2

--no-cleanup

false

--await-test-results

--text

false

--json

false

--yes

-y

false

--no-input

false

--quiet

-q

false

--no-pager

false

--debug

false

Exit Codes

0

1

9

10

11

12

130

Further Reading

• Buildkite CLI overview
• CLI command reference
• CLI installation

Optional Workflow: Act On A Failure And Check Back Later

bk build view

bk preflight --no-cleanup

bk preflight --pipeline my-org/my-pipeline --watch --no-cleanup --text

bk preflight

failing

--exit-on=build-failing

--no-cleanup

1. Wait for preflight to exit on build failing (the default --exit-on condition).
2. Inspect the failed build's jobs logs and test failures and start fixing the issue immediately.
3. Keep the build number or preflight UUID from the run output.
4. Use

   bk build view

   to check the same build again while it continues running:

bk build view <build-number> -p my-org/my-pipeline --text

1. After the build reaches a terminal state and you no longer need the remote preflight branch, clean it up explicitly:

bk preflight cleanup --pipeline my-org/my-pipeline --preflight-uuid <uuid> --yes --text

bk preflight cleanup