用 `gh` CLI 从终端调试 GitHub Actions

如果你调试 GitHub Actions 的流程是先打开三个浏览器标签页，那它大概率比实际需要的要慢。

大多数 CI 失败根本不需要 Actions 网页界面。gh CLI 让你在终端里完成核心循环：找到出问题的 run、读取失败日志、重试、实时观察。一旦用习惯了，再回到浏览器会觉得很笨拙。

找到那个 run

gh run list --limit 10

从这里开始。它会显示最近的 run、状态以及触发原因。

如果某个 workflow 一直卡在 queued，你会立刻看到。如果想用脚本处理输出，加上 --json，省去复制粘贴的功夫。

只看失败的部分

gh run view <run-id> --log-failed

这就是我一直缺少的命令。

你不总是需要完整的日志输出。通常你只需要失败的那个步骤。--log-failed 直接切到有用的部分，当你的 workflow 超过几个 job 之后，这一点非常重要。

如果确实需要所有日志，换成 --log。如果在调试 matrix build，把输出管道到 grep 继续往前走。

只重试出问题的部分

gh run rerun <run-id> --failed

这只会重新运行失败的 job，加上它们的依赖项。这通常就是你想要的。

如果失败来自一个 flaky test、registry 超时，或者其他 CI 的随机抽风，重新运行整个 workflow 纯粹是浪费时间和算力。

一个坑：你不能在 workflow 还在运行时重新执行。CLI 可能会返回一个看起来像是 workflow 文件无效的错误。实际上，很多时候只是意味着 run 还没完成。

如果你想重试某个特定的 job，先拿到正确的 ID：

gh run view <run-id> --json jobs --jq '.jobs[] | {name, databaseId}'

用 databaseId 配合 --job。不要相信自己能从网页界面随便抓一个数字然后指望它能和 CLI 预期的匹配。

实时观察

gh run watch <run-id>

这会实时流式输出 run 的进度。这是 Actions 最接近 tail -f 的东西，比每 20 秒刷新一次浏览器好太多了。

如果你已经住在终端里了，这就是缺失的那块拼图。

不推 commit 也能触发 run

gh workflow run <workflow-file>.yml --ref <branch>

如果某个 workflow 支持 workflow_dispatch，就用它。这是测试 workflow 改动最简单的方式之一，不需要创建一次性的 commit 去戳 CI。

如果你的 workflow 没有暴露 workflow_dispatch，值得改一下。手动触发让调试更容易，demo 也更干净。

浪费太多时间的 403

大量 Actions 失败归结到一件事：GITHUB_TOKEN 没有你的 workflow 需要的权限，而且错误信息通常不够清楚。

如果你的 workflow 需要写入仓库或更新 pull request，显式声明权限：

permissions:
  contents: write
  pull-requests: write

不要依赖默认值，然后在自动化执行到一半写入失败时感到意外。主动请求你需要的最小权限。

我实际在用的循环

gh run list                       # 找到 run
gh run view <run-id> --log-failed # 读取失败日志
gh run rerun <run-id> --failed    # 只重试出问题的
gh run watch <run-id>             # 实时跟踪重试

这对于日常 Actions 调试的大部分场景已经够用了。浏览器仍然有它的用处，但不需要成为你的默认选项。

完整参考：cli.github.com/manual/gh_run

用 gh CLI 从终端调试 GitHub Actions