buildkite-preflight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildkite Preflight

Preflight runs CI builds against changes in the local working directory. It's intended to provide a feedback loop for evaluating local changes in CI by providing a single command to run the entire commit/push/run loop.

Preflight 针对本地工作目录的变更运行CI构建。它旨在通过提供单一命令来完成整个提交/推送/运行流程，为在CI中评估本地变更提供反馈循环。

When to Run Preflight

何时运行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

完成要求的实现且本地测试通过后，使用preflight在CI上运行整个测试套件
在长时间无人值守的会话结束前，若已进行多项变更
修复上一次preflight运行的失败后
除非用户要求，否则不要针对拼写错误、仅注释编辑或单行配置调整等微小变更运行
当用户要求验证变更在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

优先使用
```
{org}/{pipeline}
```
格式的显式流水线
当流水线slug依赖本地配置时，确保
```
bk auth
```
指向正确的Buildkite组织
需要一个至少有一次提交且拥有
```
origin
```
推送权限的git仓库
需要
```
read_builds
```
、
```
write_builds
```
和
```
read_pipelines
```
权限范围；若要获取Test Engine结果，还需要
```
read_suites
```
权限
在子agent中运行preflight

Running Preflight

运行Preflight

bash

undefined

bash

undefined

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


Do not set a timeout on a watched preflight run.

bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 30s


不要为处于监控状态的preflight运行设置超时。

How It Works

工作原理

Preflight executes the following workflow:

Snapshot - Captures staged, unstaged, and untracked files using a temporary git index, without modifying the real index or working tree.
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.
Push - Pushes that commit to
```
refs/heads/bk/preflight/<uuid>
```
on
```
origin
```
.
Create Build - Calls the Buildkite Create Build API and sets
```
PREFLIGHT=true
```
,
```
PREFLIGHT_SOURCE_COMMIT
```
, and
```
PREFLIGHT_SOURCE_BRANCH
```
when available.
Monitor - Watches the build and emits operation events, build status updates, job failures, retry-passed jobs, and a final summary.
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.

The working tree is never disrupted, so you can keep editing while the build runs.

Preflight 执行以下工作流程：

快照 - 使用临时git索引捕获已暂存、未暂存和未跟踪的文件，不会修改真实索引或工作区。
提交 - 在
```
HEAD
```
之上创建一个独立的preflight提交，即使工作区已清理，这样运行会有自己的提交状态上下文。
推送 - 将该提交推送到
```
origin
```
的
```
refs/heads/bk/preflight/<uuid>
```
分支。
创建构建 - 调用Buildkite创建构建API，并在可用时设置
```
PREFLIGHT=true
```
、
```
PREFLIGHT_SOURCE_COMMIT
```
和
```
PREFLIGHT_SOURCE_BRANCH
```
环境变量。
监控 - 监控构建并输出操作事件、构建状态更新、任务失败、重试通过的任务以及最终摘要。
清理 - 运行结束后删除远程preflight分支，除非设置了
```
--no-cleanup
```
。默认
```
--exit-on=build-failing
```
情况下，提前退出也会取消远程构建，除非设置了
```
--no-cleanup
```
。

工作区永远不会被干扰，因此你可以在构建运行时继续编辑文件。

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.

Extracting results from the JSON build_summary event:

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'

默认退出策略为
```
build-failing
```
，因此preflight命令会在构建进入
```
failing
```
状态时立即退出。
```
--exit-on=build-terminal
```
会等待构建进入终端状态（通过、失败、取消）。
```
--await-test-results
```
会在构建完成后等待Test Engine的汇总结果（如果存在测试运行）。
最终任务摘要涵盖硬失败的脚本任务，排除非脚本、中断和软失败的任务
失败任务的输出包含任务ID。使用
```
bk job log -b <build-number> -p <org>/<pipeline> <job-id>
```
查看日志。
当有分析数据可用时，最终摘要会显示每个测试套件的通过/失败/跳过数量，以及最多10个失败测试。
测试失败会包含测试名称和位置；在本地重现失败并修复。
如果失败是不稳定的或与你的变更无关，请告知用户，而非尝试修复。

从JSON build_summary事件中提取结果：

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

使用
```
--text
```
获取纯文本日志，便于在工具输出中阅读
需要结构化事件数据时使用
```
--json
```
如果未设置任何标志，当stdout是终端时
```
bk
```
会使用交互式TTY UI，否则使用纯文本

Running a Preflight Build

运行Preflight构建

Basic usage

基础用法

bash

undefined

bash

undefined

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


Do not set a timeout on the bash tool running preflight.

bk preflight --pipeline my-org/my-pipeline --watch --await-test-results 10s


不要为运行preflight的bash工具设置超时。

Pipeline resolution

流水线解析

The

--pipeline

flag accepts either a pipeline slug or

{org slug}/{pipeline slug}

bash

undefined

--pipeline

标志接受流水线slug或

{org slug}/{pipeline slug}

格式：

bash

undefined

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

undefined

bk preflight --pipeline my-pipeline --watch

undefined

Flags

标志

Flag	Short	Default	Description
`--pipeline`	`-p`	-	Pipeline to build ( `{slug}` or `{org}/{slug}` ) (required)
`--[no-]watch`		-	Watch the build until completion
`--exit-on`		`build-failing`	Exit on `build-failing` or `build-terminal`
`--interval`		`2`	Polling interval in seconds when watching
`--no-cleanup`		`false`	Skip deleting the remote preflight branch after the build finishes
`--await-test-results`			Wait for Test Engine summaries after build completion
`--text`		`false`	Use plain text output instead of the interactive UI
`--json`		`false`	Emit one JSON object per event (JSONL)
`--yes`	`-y`	`false`	Skip all confirmation prompts
`--no-input`		`false`	Disable all interactive prompts
`--quiet`	`-q`	`false`	Suppress progress output
`--no-pager`		`false`	Disable pager for text output
`--debug`		`false`	Enable debug output for REST API calls

Flag	Short	Default	Description
`--pipeline`	`-p`	-	要构建的流水线（ `{slug}` 或 `{org}/{slug}` ）（必填）
`--[no-]watch`		-	监控构建直至完成
`--exit-on`		`build-failing`	在 `build-failing` 或 `build-terminal` 状态时退出
`--interval`		`2`	监控时的轮询间隔（秒）
`--no-cleanup`		`false`	构建完成后跳过删除远程preflight分支
`--await-test-results`			构建完成后等待Test Engine汇总结果
`--text`		`false`	使用纯文本输出替代交互式UI
`--json`		`false`	每个事件输出一个JSON对象（JSONL格式）
`--yes`	`-y`	`false`	跳过所有确认提示
`--no-input`		`false`	禁用所有交互式提示
`--quiet`	`-q`	`false`	抑制进度输出
`--no-pager`		`false`	禁用文本输出的分页器
`--debug`		`false`	启用REST API调用的调试输出

Exit Codes

退出码

Check the exit code to determine the build result:

Exit Code	Meaning	Action
`0`	All command jobs passed	Proceed with commit/push
`1`	Generic error	Check error message for details
`9`	Build completed with failures	Examine failed jobs and fix
`10`	Build incomplete but failures observed	Build still running; failures already detected
`11`	Build incomplete (scheduled/running/blocked)	Build hasn't finished yet
`12`	Unknown build state	Investigate the build on Buildkite
`130`	User aborted (Ctrl+C)	Re-run when ready

通过检查退出码判断构建结果：

Exit Code	Meaning	Action
`0`	所有命令任务均通过	继续执行提交/推送
`1`	通用错误	查看错误消息了解详情
`9`	构建完成但存在失败	检查失败任务并修复
`10`	构建未完成但已发现失败	构建仍在运行；已检测到失败
`11`	构建未完成（已调度/运行中/被阻塞）	构建尚未结束
`12`	未知构建状态	在Buildkite上调查该构建
`130`	用户中止（Ctrl+C）	准备就绪后重新运行

Optional Workflow: Act On A Failure And Check Back Later

可选工作流：处理失败并稍后复查

Begin fixing the first failure as soon as preflight exits with an incomplete build result because the build is failing, and then check back on the same build with

bk build view

for subsequent failures. This allows you to quickly iterate on the first failure, and gather further failures in parallel. Use the

bk preflight --no-cleanup

option to ensure that build is not cancled on fast failure.

bash

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

bk preflight

will return as soon as the build transitions to

failing

, using the default

--exit-on=build-failing

behavior. Setting the

--no-cleanup

flag is required if you want the build to continue running to completion.

Workflow:

Wait for preflight to exit on build failing (the default --exit-on condition).
Inspect the failed build's jobs logs and test failures and start fixing the issue immediately.
Keep the build number or preflight UUID from the run output.
Use
```
bk build view
```
to check the same build again while it continues running:

bash

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

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

bash

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

bk preflight cleanup

only deletes completed preflight branches, so run it after the build has finished.

当preflight因构建未完成且已失败而退出时，立即开始修复第一个失败，因为构建已处于失败状态，之后使用

bk build view

复查同一构建的后续失败。这让你可以快速迭代修复第一个失败，同时并行收集更多失败。使用

bk preflight --no-cleanup

选项确保构建在快速失败时不会被取消。

bash

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

bk preflight

会在构建转换为

failing

状态时立即返回，这是默认的

--exit-on=build-failing

行为。如果你希望构建继续运行至完成，必须设置

--no-cleanup

标志。

工作流：

等待preflight在构建失败时退出（默认
```
--exit-on
```
条件）。
检查失败构建的任务日志和测试失败，立即开始修复问题。
记录运行输出中的构建编号或preflight UUID。
使用
```
bk build view
```
在构建继续运行时复查同一构建：

bash

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

当构建进入终端状态且不再需要远程preflight分支时，显式清理：

bash

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

bk preflight cleanup

仅删除已完成的preflight分支，因此请在构建完成后运行。

buildkite-preflight

Original

Translation

Buildkite Preflight

Buildkite Preflight

When to Run Preflight

何时运行Preflight

Before Running

运行前准备

Running Preflight

运行Preflight

Human-readable output that works well in agent shells

Human-readable output that works well in agent shells

Start a run and return as soon as the build enters the failing state

Start a run and return as soon as the build enters the failing state

Wait for a terminal build state instead of fast-failing

Wait for a terminal build state instead of fast-failing

Start the build and exit immediately

Start the build and exit immediately

Leave the remote preflight branch and build running on early exit

Leave the remote preflight branch and build running on early exit

Wait for 30s after build completion for Test Engine summaries

Wait for 30s after build completion for Test Engine summaries

How It Works

工作原理

Reading the Result

查看结果

Output Modes

输出模式

Running a Preflight Build

运行Preflight构建

Basic usage

基础用法

Run preflight and watch until completion

Run preflight and watch until completion

Run without watching (starts the build and exits)

Run without watching (starts the build and exits)

Skip confirmation prompts (useful in scripts)

Skip confirmation prompts (useful in scripts)

Keep the remote preflight branch after the build finishes

Keep the remote preflight branch after the build finishes

Use plain text output in non-interactive environments

Use plain text output in non-interactive environments

Use JSONL output when another tool needs structured events

Use JSONL output when another tool needs structured events

Wait for 10s for Test Engine results after build completion

Wait for 10s for Test Engine results after build completion

Pipeline resolution

流水线解析

With org prefix (explicit)

With org prefix (explicit)

Pipeline slug only (org resolved from bk config)

Pipeline slug only (org resolved from bk config)

Flags

标志

Exit Codes

退出码

Further Reading

延伸阅读

Optional Workflow: Act On A Failure And Check Back Later

可选工作流：处理失败并稍后复查