DeepDojo.AI发布 2026-11-15English
用 Claude Code 排查 CI 失败的根因
一个测试在 GitHub Actions 上已经连续十次通过,这一次突然失败了。日志拉到底,最后一行报错指向的那个文件,这次提交根本没动过。
这时最容易做的事,是把最后一行报错丢给 Claude Code,让它“修一下”。可 GitHub Actions 的日志很长,最后一行往往只是后续症状;根因可能在更早的步骤里,可能在别的 job 里,也可能是一个时好时坏的不稳定测试,甚至是同一时间段里外部依赖服务出了故障。
让它照着最后一行去改,最好的结果是白忙一场,最坏的结果是把原本正常的代码改坏。
排查 CI 失败,要先回答四个问题:
- 哪个节点失败了:哪个 workflow、哪个 job、哪条命令、退出码是多少;
- 失败从什么时候开始,是否稳定复现;
- 哪次提交可能引入了问题;
- 是否已经有人在修。
这四个问题正好对应四层调查。每一层都可以交给 Claude Code 去查,但要求它每个判断都附上能复查的依据:同一提交重跑的结果、最近十几次运行的成功率、前后提交上同一检查的对比,还有已打开的修复 PR。
01 定位失败节点
先确认 workflow、job、commit、失败的命令和退出码。日志里会混着很多看起来像错误的输出,要区分清楚:warning 和不影响结果的非致命错误,与真正触发脚本退出的 failing:、fatal: 或条件判断是两回事。
开头那个“最后一行指向没动过的文件”,往往就是在这一层解开的:真正让命令以非零退出码结束的,可能是上面几十行处的一条断言。
02 判断是否不稳定
flaky 指同样的检查有时通过、有时失败。判断时要看同一个 job 最近 10 到 20 次的运行记录,只看 workflow 的总结果会误判:别的 job 失败,也会让整个 workflow 显示失败。
gh run list --workflow=<workflow-name>
gh run view <run-id> --json jobsgh run view 的 --json jobs 会列出这次运行里每个 job 的状态。你需要知道三件事:最近的成功率,上一次通过的时间,以及失败是否集中在某个时间点之后。
不同提交上有成有败,还证明不了检查本身不稳定。先比较相同提交、相同输入和环境下的重跑结果,再去调查时间、网络或资源上的差异。
回到开头那个此前连续十次通过的测试,先找同一提交的对照:
- 重跑同一个 commit,并检查输入和环境是否可比。三次里两次通过、一次失败,支持去调查不稳定因素;三次全过,也排除不了低频缺陷。
- 检查失败时间是否集中。如果多发生在凌晨,可以去调查定时任务和资源竞争,但还需要资源记录或受控的复现,才能确认具体原因。
flaky 描述的是“结果不稳定”这个现象,它本身解释不了根因。报告里写“这是 flaky”之后,还要接着写调查到哪一步了。
03 定位引入问题的提交
比较最后一次通过、第一次稳定失败以及中间的提交。首次失败附近的提交只是候选原因:依赖服务的故障,也可能恰好和某次提交同时发生。
尽量在相同的环境里,对前后提交运行同一个检查;提交较多时,用 git bisect 缩小范围。按 Git 官方文档的说明,它用二分查找定位引入 bug 的提交:你告诉它一个确认有问题的“坏”提交和一个确认没问题的“好”提交,它每次挑中间的一个让你检验,直到找到问题出现的那一次。
04 查找已有修复
用错误信息、文件名和 workflow 名称搜索已打开的 PR:
gh pr list --state open --search "<keywords>"已经有人在修时,先报告当前进展,避免重复劳动。
05 把排查交给 Claude Code
这四层可以整体交给 Claude Code,但请求里要写明按证据输出:
请分析这个 GitHub Actions 失败。
确认 workflow、job、commit、失败命令和 exit code;区分 fatal error、warning 与 flaky;
检查相关提交和已有修复 PR。每个判断都给出可验证依据。最终报告可以用这个结构:
Summary:触发 exit code 1 的直接原因。
Flakiness:重复情况与最近成功率。
Breaking Commit:能够定位时给出提交和证据。
Root Cause:日志与历史共同支持的原因。
Existing Fix PR:已有修复进展。
Recommendation:下一步修复与验证。每一栏都要对应到具体的证据。“失败时间接近某个 commit”只是一条待验证的线索,在前后 commit 上跑过同一个测试,才能进一步判断改动和失败是否有关。事实、推断和待验证项怎样在报告里分开写,Claude Code 调研报告,每条结论要有出处讲得更细。
这套流程用多了,也可以封装成一条命令。第三方仓库 ykdojo/claude-code-tips 的 dx 插件就提供了 /dx:gha <url>,传入 GitHub Actions 的链接即可按类似步骤分析;安装前同样要审查它带进来的脚本和权限。
06 等 CI 时,间歇查询就够了
CI 重跑往往要等好几分钟。等待期间不用盯着日志,用 gh run view <run-id> 间歇查询,只看目标 job:
gh run view <run-id> | grep "<job-name>"gh run watch 会持续输出,只在确实需要实时看到变化时才用。让 Claude Code 按 1、2、4、8 分钟逐次拉长间隔去查,发现明确失败再分析,多个 Claude Code 会话并行时的管理技巧里有完整的检查协议。
那个连续十次通过后突然失败的测试,走完这四层,结论可能是一次环境波动,也可能是一个低频的真实缺陷。报告里每个判断都附上能复查的依据,说不清的部分标成待确认,下一步该修代码、补测试还是等依赖恢复,也就清楚了。