
FailTrace 推出工具,可通过 URL 在本地复现失败的 GitHub Actions 运行
来源标题:FailTrace – Reproduce a failed GitHub Actions run locally from its URL
FailTrace 是一款处于早期开发阶段的工具,输入失败的 GitHub Actions 运行 URL 后,可自动定位失败的任务和步骤、匹配对应提交的工作流文件并提取日志中的失败信息。它提供 inspect、plan、repro 三个命令,其中 repro 可在 Docker 中复现 Linux 任务中以 run: 脚本失败的步骤。其定位与本地运行工作流的 act 不同,聚焦于回答某次运行为何失败及如何本地复现。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
别再猜 CI 为什么失败了,直接把它在本地复现出来。
把失败的 GitHub Actions 运行 URL 粘贴进来。FailTrace 会找出失败的那个 job 和 step,将它们对应到该 commit 上的 workflow 文件,从日志中提取出失败信息,并告诉你,要能在自己的机器上复现,还差什么。
failtrace inspect https://github.com/owner/repo/actions/runs/123456789 # why did it fail?
failtrace plan https://github.com/owner/repo/actions/runs/123456789 # how would it be reproduced?
failtrace repro https://github.com/owner/repo/actions/runs/123456789 # reproduce it in 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 上可用安装脚本安装。脚本会下载适用于你平台的最新发布版本,并校验其 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
用法
# All failed jobs in the latest attempt of a run
failtrace inspect https://github.com/owner/repo/actions/runs/123456789
# A single job (the URL you get from clicking a job in the Actions UI)
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/job/987654321
# A specific attempt of a re-run workflow
failtrace inspect https://github.com/owner/repo/actions/runs/123456789/attempts/2
# Show more log context, or emit JSON for scripts and other tools
failtrace inspect -n 60 <run-url>
failtrace inspect --json <run-url> | jq '.failed_jobs[0].failure'
Flag Default Description
--json
off
将报告输出为 JSON
-n, --lines
25
失败 step 中显示的日志行数
--job
所有失败的 job
只检查这个 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、工作目录)。显示的命令是日志中打印的那条,表达式已填充完毕。
诊断:退出码、错误注释、失败的测试名(Go、pytest、Jest、Vitest、Cargo、RSpec),以及一个分类:
复现注意事项:任何会让本地复现更困难的东西。包括 service containers、job containers、step 用到的 secrets、可复用 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> # pick a job when several failed
failtrace plan --json <run-url> # the full plan, including every env var
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 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。