技能提升网CI 红了以后，群里最常见的消息是“构建挂了，可能是依赖问题”。发消息的人已经试过重跑、改缓存、换版本，却没有记录每次尝试的结果。下一位接手者只能重新打开日志，从头猜一次。
排查记录不是粘贴整段日志。它要让别人知道在哪个仓库、哪个提交、哪个工作流和哪个步骤失败，怎样用最短路径复现，以及哪些假设已经被排除。
先冻结一次失败现场
记录仓库、分支、提交 SHA、工作流名称、运行 ID、触发方式和失败时间。随后定位失败 job 与 step，保留错误前后的关键日志。只写“测试失败”不够，同一工作流可能包含多种环境和矩阵任务。
GitHub 官方文档说明可以在工作流运行页面查看 job 日志、搜索日志并下载日志文件。需要重跑时，也应保留原运行信息，避免新一次结果覆盖对旧现场的描述。
把现象、假设和实验分开
现象是日志中已经发生的事实，例如某个命令退出码为 1。假设是对原因的解释，例如锁文件与缓存不一致。实验是为验证假设而做的最小改动。三者混在一句话里，接手者看不出哪部分已经证实。
| 记录 | 示例 |
|---|---|
| 现象 | ubuntu-latest 的 test job 在依赖安装步骤退出 |
| 证据 | 运行 ID、步骤名、关键错误行和退出码 |
| 假设 | 缓存键未包含锁文件变化 |
| 实验 | 禁用缓存后重跑同一提交 |
| 结果 | 失败仍存在，排除缓存作为唯一原因 |
用 Github Skill 取结构化信息
Github Skill 指导 AI 使用 GitHub 官方 gh 命令行查看 Pull Request 检查结果、列出 Actions 运行、读取失败日志并通过 JSON 输出整理字段。操作不在目标仓库目录时，要明确 owner/repo，避免查错项目。
请读取指定仓库和运行 ID 的 CI 失败信息。
记录仓库、分支、提交 SHA、工作流、运行 ID、触发方式、失败 job 和 step。
只摘取与失败直接相关的日志片段，保留退出码和必要上下文。
分开列出现象、当前假设、验证实验和结果。
不要自动重跑、修改工作流、提交代码或泄露令牌。
如果需要写入操作，先说明目标仓库、影响和恢复方式。只读查询也要使用最小权限令牌，不能把访问令牌写进命令输出、日志或仓库文件。涉及私有仓库时，排查记录的分享范围要与代码权限一致。
复现步骤从干净环境开始
“在我电脑上也失败”不能帮助别人复现。记录操作系统、运行时版本、包管理器、锁文件状态、必要服务和环境变量名称。敏感值只说明如何安全提供，不写入文档。
从干净检出开始，按最少命令复现。如果本地无法复现，记录差异，例如 CI 使用的镜像、权限、网络、时区、文件系统大小写或并发设置。不要为了让步骤变短而省略会改变结果的前置条件。
重跑前先说明目的
重跑可以判断偶发故障，但它也会消耗资源，并可能让团队误以为问题已经解决。每次重跑要关联一个假设，例如验证外部服务短暂不可用，或确认失败是否只出现在某个矩阵环境。没有假设的连续重跑，只是在等待绿色结果。
GitHub 支持为 runner 和 step 开启额外调试日志。日志可能包含更多环境信息，开启前要检查机密遮盖和分享范围，问题定位后及时关闭。
修复完成后保留反证
最终记录要说明改了什么、为什么这能解释原失败、用哪次运行验证，以及还有哪些风险未覆盖。如果只是重跑变绿，结论应写“暂未复现”，不要写“已修复”。
一份好的 CI 记录会缩短下一次排查：别人不必重读完整日志，也不会重复已经失败的实验。它留下的是可复现路径和证据，不是某个人当时的猜测。
