
FailTrace:从 GitHub Actions 失败链接在本地复现 CI 故障
来源标题:FailTrace – Reproduce a failed GitHub Actions run locally from its URL
开源工具 FailTrace 可粘贴 GitHub Actions 失败运行链接,定位失败的 job 和步骤,并支持在 Docker 中复现。三条命令 inspect、plan、repro 均已可用,目前 repro 仅覆盖失败步骤为 run 脚本的 Linux 任务。项目处于早期开发阶段,与本地运行工作流的 act 定位不同,专注回答这次运行为何失败、能否在本地复现。
以下正文由 AI 翻译自 Hacker News(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
别再猜 CI 为什么失败了,直接在本地复现它。
粘贴一个失败的 GitHub Actions 运行 URL。FailTrace 会找出失败的是哪个 job 和哪个 step,把它们对应到该 commit 上的 workflow 文件,从日志里提取出失败原因,并告诉你要在自己的机器上复现还差什么。
failtrace inspect https://github.com/owner/repo/actions/runs/123456789 # 为什么失败? failtrace plan https://github.com/owner/repo/actions/runs/123456789 # 该怎么复现? failtrace repro https://github.com/owner/repo/actions/runs/123456789 # 在 Docker 里复现
状态:早期开发阶段。三个命令都能用。repro 目前只覆盖 Linux job,且失败的 step 必须是 run: 脚本。见 roadmap 和 limitations。
act 在本地运行 workflow,这方面它很擅长。FailTrace 回答的是另一个问题:这一次运行为什么失败,我能不能在本地让它以同样的方式失败?
一个失败的 prometheus/prometheus 运行的真实输出(有删减):
✗ CI · prometheus/prometheus "remote/otlp: remove delta-to-cumulative conversion" pull_request · on codex/remove-otlp-deltatocumulative · @ cf7d324 · attempt 1 · failure ──────────────────────────────────────────────────────────── ✗ Job: Go tests (failure) Runner ubuntu-latest → ubuntu-26.04 (20261116.202.1) · runner 2.338.2 Workflow .github/workflows/ci.yml → jobs.test_go Steps ✓ 5 Run make GO_ONLY=1 SKIP_GOLANGCI_LINT=1 ✓ 6 Run go test ./tsdb/ -test.tsdb-isolation=false ✗ 7 Run make -C documentation/examples/remote_storage ← failed here ○ 8 Run make -C documentation/examples (skipped) Failed step #7 Run make -C documentation/examples/remote_storage shell: sh -e {0} $ make -C documentation/examples/remote_storage Diagnosis files out of date (a check produced a git diff) · exit code 2 Log excerpt (10 lines around the first error in "Run make -C documentation/examples/remote_storage") │ >> running check for unused/missing packages in go.mod │ go mod tidy │ go: downloading github.com/oapi-codegen/nullable v1.1.0 │ diff --git a/documentation/examples/remote_storage/go.mod b/documentation/examples/remote_storage/go.mod │ --- a/documentation/examples/remote_storage/go.mod │ +++ b/documentation/examples/remote_storage/go.mod Reproduction notes ! job runs inside container quay.io/prometheus/golang-builder:1.27-base
日志末尾是几百行 go.sum diff。FailTrace 把摘录定位在第一条错误行附近,这样你看到的是原因——go mod tidy 改动了 go.mod——而不是它后面的噪音。
使用安装脚本,支持 macOS 和 Linux。脚本会下载对应平台的最新 release,并校验其 SHA-256:
curl -fsSL https://raw.githubusercontent.com/Ri4dH/failtrace/main/scripts/install.sh | sh
如果 /usr/local/bin 可写就装到那里,否则装到 ~/.local/bin。可以用 FAILTRACE_INSTALL_DIR 指定目录,或用 FAILTRACE_VERSION=v0.1.0 固定版本。
macOS、Linux 和 Windows(amd64 和 arm64)的预编译二进制在 releases 页面,附有 checksums.txt。
go install github.com/Ri4dH/failtrace/cmd/failtrace@latest
从源码构建:
git clone https://github.com/Ri4dH/failtrace cd failtrace go build -o bin/failtrace ./cmd/failtrace
用法
一次运行最新 attempt 里的所有失败 job
failtrace inspect https://github.com/owner/repo/actions/runs/123456789
单个 job(在 Actions UI 里点击某个 job 得到的 URL)
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/job/987654321
重跑过的 workflow 的某个特定 attempt
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/attempts/2
显示更多日志上下文,或输出 JSON 给脚本和其他工具用
failtrace inspect -n 60 <run-url> failtrace inspect --json <run-url> | jq '.failed_jobs[0].failure'
Flag Default Description --json off Print the report as JSON -n, --lines 25 Log lines to show from the failed step --job all failed Inspect only this job ID
当 stdout 不是终端,或设置了 NO_COLOR 时,彩色输出会自动关闭。
FailTrace 需要一个 GitHub token,即使是公开仓库也需要,因为日志 API 要求提供。它按以下顺序查找:
私有仓库需要一个能读取该仓库 Actions 的 token。GitHub Enterprise Server 的 URL 也支持:API base 会变成 https://<host>/api/v3。
运行上下文:workflow、event、branch、commit、attempt。
Job → workflow 映射:找到 job 定义,包括命名为 test (ubuntu-latest, 1.22) 或 Lint ${{ matrix.tool }} 这样的 job,并还原 matrix 取值。
Runner:请求的 label 以及实际 runner 镜像和版本,从日志中得出。
失败的 step:它的定义(run、uses、with、env、shell、working directory)。显示的命令是日志里打印的那条,表达式已经填入。
诊断:退出码、错误注解、失败的测试名(Go、pytest、Jest、Vitest、Cargo、RSpec),以及一个类别:
复现说明:任何会让本地复现更困难的因素。也就是 service container、job container、step 用到的 secret、可复用 workflow,以及 macOS 或 Windows runner。
它还会解释边界情况,而不是默默失败:在任何 job 开始前就失败的运行、仓库里没有对应文件的动态 workflow,以及已过期的日志。
failtrace plan 会算出如何在本地复现失败的 job,并打印计划。它目前还不会执行任何东西。
failtrace plan https://github.com/owner/repo/actions/runs/123456789 failtrace plan --job 987654321 <run-url> # 有多个 job 失败时选一个 failtrace plan --json <run-url> # 完整计划,包括每个环境变量
一个失败的 pytest-dev/pytest job 的真实输出(有删减):
Reproduction plan · pytest-dev/pytest Job build (ubuntu-py311) (jobs.build) Verdict PARTIAL: can run, but the warnings below may make it differ from CI Image ubuntu:26.04 linux/amd64 matches the runner image ubuntu-26.04 20261111.196.1 Commit c484767 Toolchains python 3.11.18 exact · asked for "3.11" · from actions/setup-python@6d4fd22 uv 0.13.8 exact · from astral-sh/setup-uv@11f9893 Steps
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。