github-actions-failure-debugging

jtakumi 的头像作者 jtakumi

GitHub Actions工作流程失败调试指南。当CI失败、Actions上的测试失败或日志显示退出代码不等于0时使用。

📖 中文导读:GitHub Actions工作流程失败调试指南。当CI失败、Actions上的测试失败或日志显示退出代码不等于0时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: github-actions-failure-debugging description: Debug guide for failing GitHub Actions workflows. Use when CI fails, tests fail on Actions, or logs show exit code != 0.

Goals

  • Identify the first failing step and the real root cause (not the cascade).
  • Produce a minimal fix (workflow or code) and re-run checks.

Procedure

  1. Find the failing workflow run and the failing job/step. Extract:
    • runner OS, language/runtime versions, cache usage
    • exact command that failed
  2. Classify failure:
    • build tool / dependency resolution
    • test failure
    • lint/static analysis
    • auth/permissions/secrets
  3. Reproduce locally when possible:
    • use the same command as the workflow
    • if not possible, provide a deterministic reproduction plan.
  4. Fix strategy:
    • prefer smallest change
    • avoid disabling checks unless justified
  5. Verification:
    • ensure job matrix still passes
    • update docs if workflow usage changed

Output format

  • Root cause (1-2 sentences)
  • Evidence (log excerpt references)
  • Fix diff + why it works
  • How to validate (exact commands)