GitHub CI/CD 常见故障怎么排查？问题定位与维护清单

故障排查的前提：理解GitHub Actions的执行模型

排查GitHub CI/CD故障，首先要理解它的执行模型。GitHub Actions的每次运行都是一个工作流（Workflow），由事件触发，在Runner上按步骤执行。Runner可以是GitHub托管的，也可以是自托管的。常见故障大部分集中在这几个环节：触发阶段、环境准备阶段、依赖安装阶段、测试或构建阶段、以及部署阶段。

很多团队在排查时直接看日志的最后几行，这种做法在简单错误（如语法错误）时有效，但在缓存问题、Runner资源不足或Secrets过期等场景下，往往给出误导信息。正确的做法是先确认故障发生的阶段，再按阶段去检查对应的配置和环境。

本文不讨论每一个Action的具体用法，而是聚焦于故障分类、排查顺序、证据保留和长期治理。这些内容来自多个长期运行的CI/CD项目经验，涉及团队规模从几人到几十人不等，适用于中小型到中型企业。

故障分类：六类最常见的问题

根据过往项目中的高频故障，可以将GitHub CI/CD问题归为六类。每一类的根因和表现都有明显特征。

1. 构建脚本或配置语法错误

这类错误最直观，工作流在启动阶段就失败。表现为YAML缩进错误、Action版本号无效、步骤名称重复、或者使用了不存在的环境变量。GitHub会在日志中明确标注行号，修复难度低。

但有一个容易被忽略的点：某些语法错误只在特定触发条件下才会暴露。例如，一个工作流只在push到`main`分支时执行，但语法错误却在`pull_request`事件中才出现——因为YAML中的条件判断写错了。排查时，应手动触发一次完整的工作流，而不是依赖事件触发。

2. 依赖安装与缓存失效

这是最消耗排查时间的一类问题。表现包括：构建时提示包找不到、版本冲突、或者缓存命中但内容不完整。常见原因有：

• `actions/cache`的key设计不合理，导致不同分支共享了不应该共享的缓存。
• 缓存未随`package-lock.json`或`Gemfile.lock`的更新而失效。
• 自托管Runner上残留了旧版本工具链，与缓存中的二进制文件不兼容。

排查时，建议先禁用缓存跑一次完整构建，确认问题是否与缓存相关。如果是，再检查缓存key的生成逻辑。一般来说，缓存key应该包含锁文件的哈希值，并且恢复key应做分层设计，避免跨分支污染。

3. Runner资源不足或网络故障

GitHub托管的Runner有明确的资源限制：每个Job最多运行6小时，单次构建可用内存和CPU也有限制。常见故障包括：构建过程中Runner被回收、OOM（内存溢出）、磁盘空间不足、或者无法拉取外部依赖。

自托管Runner的问题更复杂：Runner进程可能因系统更新而停止、网络代理配置错误、或者Runner注册Token过期。排查时，先检查Runner的状态页（Settings > Actions > Runners），确认Runner在线且标签正确。

如果Runner在构建中途断开，日志会显示“Lost communication with the server”或类似信息。此时需要检查Runner所在机器的网络稳定性，以及是否被防火墙或代理中断了长连接。

4. Secrets与环境变量配置错误

Secrets在GitHub Actions中是以加密形式存储的，但一旦被错误引用或未定义，工作流可能静默失败或使用默认值。常见场景：

• 在`env`块中引用了未定义的Secrets，导致变量值为空。
• 多环境部署时，不同分支使用了同一组Secrets，导致生产环境使用了测试环境的密钥。
• Secrets在仓库设置中被删除或修改，但工作流未同步更新。

排查这类问题时，可以在工作流中添加一个调试步骤，打印环境变量的长度或是否存在，但注意不要直接输出Secrets的值——GitHub会自动将Secrets的值替换为`***`。更好的做法是使用`if`条件判断变量是否为空，并显式失败。

5. 权限与Token问题

当工作流需要访问其他仓库、创建Release、或部署到云服务时，通常需要`GITHUB_TOKEN`或Personal Access Token（PAT）。权限不足的典型表现是：push操作失败、无法创建Issues、或者API调用返回403。

`GITHUB_TOKEN`的权限范围是有限的，默认只有当前仓库的读写权限。如果需要跨仓库操作，必须使用PAT，并确保PAT具有正确的scope。此外，Token过期也是一个常见问题——PAT有有效期，而`GITHUB_TOKEN`在每个工作流运行结束时自动失效。

排查时，检查日志中是否有“Resource not accessible by integration”或“403”错误。如果是，先确认Token是否存在、是否过期、以及是否被正确传递到Action中。

6. 工作流触发条件与并发冲突

这类问题往往被忽视，直到出现“构建队列堆积”或“重复部署”时才被发现。常见情况包括：

• `push`和`pull_request`事件同时触发，导致同一个代码变更被构建两次。
• `workflow_dispatch`事件未限制分支，导致任何人都可以手动触发生产部署。
• 并发构建导致资源竞争，例如数据库迁移被同时执行两次。

排查时，检查工作流的`on`配置，确认触发条件是否过于宽泛。使用`concurrency`配置可以限制同一分支上的并发构建数，避免资源竞争。

排查顺序：从外到内，从简单到复杂

当故障发生时，建议按照以下顺序排查，避免在复杂问题上浪费过多时间。

第一步：确认故障是否在GitHub端

先访问GitHub Status页面（https://www.githubstatus.com/），确认Actions服务是否正常。虽然这种情况不常见，但确实发生过。如果GitHub端有故障，无需进一步排查。

第二步：检查工作流日志的总体状态

在仓库的Actions页面，找到失败的工作流运行。点击进入后，先看Job级别的状态，再看Step级别的状态。GitHub会在失败的Step上标红。这一步可以快速定位故障发生的阶段。

第三步：定位故障阶段

根据失败的Step名称，判断故障属于哪个阶段：

• 如果失败在“Set up job”阶段，通常是Runner或环境问题。
• 如果失败在“Run actions/checkout”阶段，可能是网络或权限问题。
• 如果失败在自定义的构建或测试步骤，则检查脚本和依赖。

第四步：检查日志中的关键错误信息

不要只看最后几行。建议搜索以下关键词：`error`、`failure`、`exit code 1`、`not found`、`permission denied`、`timeout`。这些关键词通常指向根因。同时，注意日志中是否有`Warning`信息——有些Warning是正常的，但有些预示着未来可能失败。

第五步：重现问题

如果从日志中无法直接定位根因，尝试在本地或测试环境中重现问题。对于依赖安装问题，可以在本地运行相同的命令。对于缓存问题，可以手动清除缓存后重新构建。

重现时，尽量使用与CI/CD环境相同的操作系统和工具版本。GitHub托管的Runner使用Ubuntu 22.04或24.04，如果本地是macOS，环境差异可能导致问题无法重现。

第六步：检查配置变更历史

如果故障是突然出现的，检查最近一次成功运行和第一次失败运行之间的配置变更。包括工作流YAML文件的变更、Secrets的修改、Runner的更新、以及依赖版本的变化。GitHub提供工作流运行之间的Diff视图，可以直接对比。

证据保留：让每一次故障都留下可追溯的记录

很多团队在排查故障时，只关注“修好”，忽略“记录”。这导致同一类问题反复出现。以下是在故障发生时应该保留的证据：

工作流运行日志

GitHub默认保存工作流运行日志90天（企业版可能更长）。建议在故障发生时，立即下载日志文件（Actions页面右上角的“Download log archive”）。日志包含每个步骤的控制台输出，是排查的第一手资料。

Runner系统日志

对于自托管Runner，需要保留Runner所在机器的系统日志。包括`journalctl`输出、Runner的`svc.log`文件、以及系统资源监控数据（CPU、内存、磁盘I/O）。这些日志可以帮助判断Runner是否因资源耗尽而被杀死。

构建产物

如果工作流生成了构建产物（如二进制文件或Docker镜像），建议在故障发生时保留这些产物。它们可能包含调试信息。对于测试失败的情况，保留测试报告和截图。

环境快照

记录故障发生时的工作流环境信息：GitHub Actions的版本、Runner的操作系统版本、使用的Action版本、以及依赖的版本。这些信息可以通过在工作流中添加一个步骤来收集：

```yaml

• name: Collect environment info

run: |
echo "OS: $(uname -a)"
echo "Node: $(node --version 2>/dev/null)"
echo "Docker: $(docker --version 2>/dev/null)"
echo "GitHub ref: ${{ github.ref }}"
```

这一步不会影响构建结果，但能提供关键的环境上下文。

时间线记录

记录故障发生的时间、持续时长、以及是否与其他事件（如代码合并、Secrets更新、Runner重启）同时发生。时间线可以帮助判断故障是否由外部变更触发。

长期治理：从被动救火到主动预防

故障排查的最终目标不是“修好”，而是“不再发生”。以下治理措施来自多个项目的实践经验，适用于已经运行半年以上的CI/CD管道。

建立故障分类与优先级矩阵

将已经遇到过的故障按影响范围、发生频率、修复难度分类。例如：

| 故障类型 | 影响范围 | 发生频率 | 修复难度 | 治理优先级 |
|---|---|---|---|---|
| 缓存失效 | 单次构建 | 高 | 低 | 高 |
| Runner离线 | 所有构建 | 低 | 中 | 高 |
| Secrets过期 | 特定环境 | 中 | 低 | 中 |

基于这个矩阵，优先治理高频且影响大的问题。对于缓存失效，可以通过改进缓存key设计来降低频率。对于Runner离线，可以设置监控告警。

实施构建健康检查

在每次构建完成后，自动检查构建结果。如果连续失败超过一定次数（例如3次），自动暂停工作流并通知维护者。GitHub Actions支持通过`if: failure()`条件来发送通知，也可以结合Slack或邮件告警。

健康检查还包括构建时间的监控。如果某个Job的构建时间突然增加50%以上，可能预示着依赖安装变慢或Runner资源不足，即使构建通过，也应该主动排查。

定期审计工作流配置

每季度或每半年审计一次工作流配置。检查内容：

• 使用的Action版本是否需要更新（关注Security Advisories）。
• Secrets是否已过期或被删除。
• 触发条件是否仍然合理（例如，是否还有不需要的`push`事件）。
• 缓存key是否需要调整。
• 权限配置是否最小化。

审计结果应该以Pull Request的形式提交，并附带变更说明。

建立回滚与重试机制

对于部署阶段的工作流，必须建立回滚机制。GitHub Actions本身支持部署到多个环境，并且可以通过`environment`配置来设置审批门。如果部署失败，应该自动触发回滚步骤。

重试机制也很重要。对于网络超时或临时资源不足导致的失败，可以在工作流中添加重试逻辑。GitHub Actions不直接支持Step级别的重试，但可以通过`if: failure()`和`continue-on-error`组合实现简单的重试，或者使用第三方Action如`nick-fields/retry`。

文档化常见故障与解决方案

将排查过程中发现的常见故障和解决方案编写成文档，放在仓库的`docs/`目录下。文档应该包含：

• 故障现象（日志关键信息）
• 根因分析
• 解决方案
• 预防措施

新成员加入团队时，这份文档可以大大缩短上手时间。在SystemDo的多个项目中，我们发现文档化的故障库能将平均排查时间从2小时降低到30分钟以内。

维护清单：日常巡检与应急响应

以下是一份可直接使用的维护清单，适用于每周或每两周执行一次。

日常巡检（每周）

• [ ] 检查所有工作流最近一周的运行状态，是否有异常失败。
• [ ] 检查自托管Runner的状态，确认所有Runner在线且标签正确。
• [ ] 检查Secrets的过期时间，提前更新即将过期的Token。
• [ ] 检查缓存命中率，如果命中率低于60%，优化缓存key设计。
• [ ] 检查构建时间，对比上周是否有显著增加。

月度维护

• [ ] 更新工作流中使用的Action到最新稳定版本。
• [ ] 清理过期的构建产物和日志（如果存储空间有限）。
• [ ] 审计工作流配置，删除不再使用的Job或Step。
• [ ] 检查权限配置，移除不再需要的Token或SSH密钥。

应急响应流程

当故障发生且影响生产部署时，按以下步骤执行：

1. 暂停所有受影响的工作流（在仓库Settings > Actions中禁用）。
2. 确认故障是否由代码变更引起，如果是，回滚代码。
3. 按照排查顺序定位根因。
4. 修复后，先在一个非生产分支上验证。
5. 验证通过后，重新启用工作流并部署。
6. 记录故障信息到文档。

总结：排查能力来自系统化积累

GitHub CI/CD的故障排查不是一次性的技术活动，而是需要持续投入的工程实践。每一次故障都是一次学习机会，关键在于保留证据、分析根因、并改进流程。当团队建立起故障分类、排查顺序、证据保留和长期治理的闭环后，CI/CD管道会越来越稳定，故障恢复时间会越来越短。

对于已经运行了半年以上的CI/CD管道，建议至少进行一次全面的审计，识别出那些“经常失败但没人修”的步骤。这些步骤往往是管道中最脆弱的部分，也是治理后收益最高的地方。