fix-buildkite-ci

修复 Buildkite CI

概述

以编程方式诊断 Buildkite 失败，不要根据 UI 截图猜测。优先使用结构化的构建/作业 JSON 和产物检查，找出确切失败的测试用例及不匹配内容，然后实施最小且正确的修复。

目标选择

按以下优先级确定排查目标：

• 如果用户提供了 Buildkite 构建 URL，直接使用该构建。
• 否则，如果用户指定了分支和/或流水线（例如 pull-request、main-cron），使用指定范围。
• 否则，默认使用当前 Git 分支，并检查与该分支关联的 PR 的检查项。

工作流

1. 确定失败的 Buildkite 构建。
2. 获取构建 JSON，并列出失败的作业。
3. 拉取作业日志，提取第一个明确的失败信号。
4. 如果顶层日志被截断，则检查产物。
5. 将失败归因于根本原因，并进行有针对性的修复。
6. 尽可能在本地验证，并总结证据。

优先使用 bk CLI。如果无法进行身份验证，则使用公开的 Buildkite JSON/日志/产物端点，通过 curl 获取信息。

具体命令和端点模式见 references/buildkite-ci-triage.md。

第 1 步：确定失败的 Buildkite 检查项

未明确指定目标时，先查找当前分支对应的 PR，然后运行 gh pr checks <PR_NUMBER>，找出失败的检查项并记录 Buildkite URL（.../builds/<N>）。

如果用户指定了分支/流水线，则使用这些参数运行 bk build list，列出并筛选构建。 如果用户提供了 Buildkite 构建 URL，则跳过发现步骤，从该构建编号开始排查。

第 2 步：获取构建 JSON 和失败的作业

获取 builds/<N>.json，然后根据非零 exit_status 列出失败的作业。

至少记录以下信息：

• 流水线
• 构建编号
• 作业 ID
• 作业名称
• 退出状态

第 3 步：提取明确的失败信息

获取每个失败作业的日志，并搜索高信号模式：

• query result mismatch
• [Diff] (-expected|+actual)
• query is expected to fail with error:
• panic/断言行
• 确定性模拟错误标记
• OOM/超时/取消标记

找到一个明确失败的文件/用例及其不匹配内容后即可停止。

第 4 步：检查产物

如果日志只显示包装器错误（例如，命令以某个状态退出），则检查同一作业的产物，尤其是：

• risedev-logs.zip
• risedev-logs/nodetype-*.log

提取产物日志并搜索确切的不匹配内容。

第 5 步：进行有针对性的修复

优先采用有证据支持的最小修复：

• SQLLogicTest 不匹配：仅当查询输出变化是有意的，才更新正确的 .slt/.slt.part 文件中的预期部分。
• 运行时行为错误：修复源代码，测试保持不变。
• 仅有偶发失败/取消信号（143）：将其视为基础设施/取消问题，除非有产品错误佐证。

如果没有根本原因证据，避免采取宽泛的“重试碰碰运气”操作。

第 6 步：验证并报告

尽可能运行范围最小、足以验证修复的本地检查。如果无法进行完整验证，请明确说明。

始终报告：

• 失败的检查项/构建/作业标识符
• 失败的文件/测试/用例
• 确切的不匹配/错误证据
• 已实施的修复（更改的文件）
• 验证状态和剩余风险

Buildkite 专用经验法则

• 退出代码 105：通常是 docker-compose/插件引起的包装器失败；检查 SLT/e2e 日志以查明真实的不匹配。
• 退出代码 4：模拟/恢复步骤中常见；检查上传的模拟日志。
• 退出代码 143：通常表示取消/终止，而非确定性的产品回归。
• JSON 中的 raw_log_url 可能为 null；请使用按作业 ID 指定的作业日志端点。
• 优先使用 JSON 端点和 jq；避免抓取大型 HTML 页面。