buildkite-preflight

Buildkite 预检

预检会针对本地工作树中的更改运行 CI 构建。它旨在通过一个命令完成整个提交／推送／运行流程，为评估本地更改提供 CI 反馈循环。

何时运行预检

• 完成所需的实现并通过本地测试后，使用预检在 CI 上运行完整测试套件
• 在较长的无人值守会话结束前，如果你做了多项更改
• 修复上一次预检运行中的失败后
• 不要用于错别字、仅注释的编辑或单行配置调整等琐碎更改，除非用户提出要求
• 用户要求验证更改能否在 CI 中正常运行时

运行前

• 优先使用 {org}/{pipeline} 格式的显式流水线
• 如果流水线 slug 依赖本地配置，请确保 bk auth 指向正确的 Buildkite 组织
• 需要使用至少有一次提交且可推送到 origin 的 git 仓库
• 需要 read_builds、write_builds 和 read_pipelines 作用域；获取 Test Engine 结果还需要 read_suites。
• 在子 Agent 中运行预检

运行预检

# 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

监控预检运行时不要设置超时。

工作原理

预检会执行以下工作流：

1. 快照 - 使用临时 git 索引捕获已暂存、未暂存和未跟踪的文件，不修改真实索引或工作树。
2. 提交 - 在 HEAD 之上创建独立的预检提交，即使工作树干净也会创建，以便本次运行拥有自己的提交状态上下文。
3. 推送 - 将该提交推送到 origin 上的 refs/heads/bk/preflight/<uuid>。
4. 创建构建 - 调用 Buildkite Create Build API，并在可用时设置 PREFLIGHT=true、PREFLIGHT_SOURCE_COMMIT 和 PREFLIGHT_SOURCE_BRANCH。
5. 监控 - 监控构建并输出操作事件、构建状态更新、作业失败、重试后通过的作业以及最终摘要。
6. 清理 - 运行结束时删除远程预检分支，除非设置了 --no-cleanup。使用默认的 --exit-on=build-failing 时，提前退出也会取消远程构建，除非设置了 --no-cleanup。

预检不会干扰工作树，因此构建运行期间你可以继续编辑。

查看结果

• 默认退出策略是 build-failing，因此构建进入 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'

输出模式

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

运行预检构建

基本用法

# 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

运行预检的 bash 工具不要设置超时。

流水线解析

--pipeline 标志接受流水线 slug 或 {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

标志

标志	短标志	默认值	描述
--pipeline	-p	-	要构建的流水线（{slug} 或 {org}/{slug}）（必需）
--[no-]watch		-	持续监视构建，直到完成
--exit-on		build-failing	遇到 build-failing 或 build-terminal 时退出
--interval		2	监视时的轮询间隔，单位为秒
--no-cleanup		false	构建完成后跳过删除远程预检分支
--await-test-results			构建完成后等待 Test Engine 摘要
--text		false	使用纯文本输出，而非交互式界面
--json		false	每个事件输出一个 JSON 对象（JSONL）
--yes	-y	false	跳过所有确认提示
--no-input		false	禁用所有交互式提示
--quiet	-q	false	隐藏进度输出
--no-pager		false	禁用文本输出的分页器
--debug		false	启用 REST API 调用的调试输出

退出代码

检查退出代码以确定构建结果：

退出代码	含义	操作
0	所有命令作业均已通过	继续提交/推送
1	一般错误	查看错误消息以了解详情
9	构建已完成，但存在失败	检查失败的作业并修复
10	构建尚未完成，但已发现失败	构建仍在运行；已检测到失败
11	构建尚未完成（已安排/正在运行/受阻）	构建尚未结束
12	未知构建状态	在 Buildkite 上调查该构建
130	用户中止（Ctrl+C）	准备好后重新运行

延伸阅读

• Buildkite CLI 概览
• CLI 命令参考
• CLI 安装

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

如果预检因构建失败而以未完成的构建结果退出，请立即开始修复第一个失败项。在构建继续运行期间查看同一构建的摘要，然后直接查询失败的作业以查找后续失败项。这样可以快速迭代修复第一个失败项，同时并行收集其他失败信息。使用 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. 等待预检在构建失败时退出（默认的 --exit-on 条件）。
2. 检查失败构建的作业日志和测试失败项，并立即开始修复问题。
3. 记下本次运行输出中的构建编号或预检 UUID。
4. 检查构建状态，但不要下载作业、制品、注释或展开的流水线详情。通过 REST List Jobs 端点单独查询失败的作业：

bk build view 429 -p my-org/my-pipeline --summary --text
bk job list --pipeline my-org/my-pipeline --build 429 --state failed --no-limit --text

5. 构建进入终止状态且不再需要远程预检分支后，显式清理该分支：

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

bk preflight cleanup 只会删除已完成的预检分支，因此请在构建结束后运行此命令。