FailTrace
别再猜 CI 为什么失败了。在本地复现它。

粘贴一个失败的 GitHub Actions 运行 URL。FailTrace 会找到失败的 job 和 step,将它们匹配到该确切提交处的 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: 脚本。参见路线图和限制。
为什么不用 act?
act 在本地运行你的 workflow,这方面它很擅长。FailTrace 回答的是另一个问题:为什么这次特定的运行失败了,以及我能不能在这里让它以同样的方式失败?
- 它从一次失败的运行开始,而不是从 workflow 文件开始。你会得到确切的提交、尝试次数、job、矩阵组合和失败的 step。无需配置。
- 它聚焦于失败。目标是只重放失败 step 所需的内容,而不是整个 workflow。
- 它给你一个判定。现在你会得到诊断。之后你还会得到已复现 / 未复现 / 不稳定,以及 CI 和你的机器之间的差异。
示例
一个失败的 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 1.24+:
go install github.com/Ri4dH/failtrace/cmd/failtrace@latest
从源码:
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都要完全按原样使用它们:它们会在任何东西运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。
文章标题:FailTrace – 从 URL 在本地复现失败的 GitHub Actions 运行
正文:
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'
| 参数 | 默认值 | 说明 |
|---|---|---|
| --json | 关闭 | 以 JSON 格式输出报告 |
| -n, --lines | 25 | 显示失败步骤的日志行数 |
| --job | 所有失败的作业 | 只检查指定的作业 ID |
当 stdout 不是终端,或设置了 NO_COLOR 时,彩色输出会自动关闭。
认证
即使是公开仓库,FailTrace 也需要一个 GitHub token,因为日志 API 需要它。它按以下顺序查找:
- GITHUB_TOKEN
- gh auth token(如果你使用 GitHub CLI,这一项已经可用)
私有仓库需要一个对该仓库有 Actions 读取权限的 token。GitHub Enterprise Server 的 URL 也支持:API 基础地址会变成 https://<host>/api/v3。
inspect 报告的内容
- 运行上下文:workflow、event、branch、commit、attempt。
- 作业 → workflow 映射:找到作业定义,包括命名为 test (ubuntu-latest, 1.22) 或 Lint ${{ matrix.tool }} 这类作业,并还原矩阵值。
- Runner:从日志中获取请求的标签,以及实际使用的 runner 镜像和版本。
- 失败步骤:其定义(run、uses、with、env、shell、工作目录)。显示的命令是日志中打印的那条,表达式已经填入。
- 诊断:退出码、错误注解、失败的测试名(Go、pytest、Jest、Vitest、Cargo、RSpec),以及一个类别:类别 示例信号 test --- FAIL: TestX, FAILED tests/x.py::test_y build error TS2304, undefined: foo, error[E0425] dependency npm ERR! code ERESOLVE, missing go.sum entry lint golangci-lint, eslint, ruff steps generated-diff a check that printed diff --git (tidy, codegen, formatters) timeout exceeded the maximum execution time out-of-memory exit code 137, heap out of memory
诊断:退出码、错误注解、失败的测试名(Go、pytest、Jest、Vitest、Cargo、RSpec),以及一个类别:
| 类别 | 示例信号 |
|---|---|
| test | --- FAIL: TestX , FAILED tests/x.py::test_y |
| build | error TS2304 , undefined: foo , error[E0425] |
| dependency | npm ERR! code ERESOLVE , missing go.sum entry |
| lint | golangci-lint , eslint , ruff steps |
| generated-diff | a check that printed diff --git (tidy, codegen, formatters) |
| timeout | exceeded the maximum execution time |
| out-of-memory | exit code 137, heap out of memory |
- 复现说明:任何会让本地复现变得更困难的因素。也就是说,service 容器、job 容器、步骤使用的 secrets、可复用 workflow,以及 macOS 或 Windows runner。
它还会解释边缘情况,而不是静默失败:在任何作业开始前就已失败的运行、仓库中没有对应文件的动态 workflow,以及已过期的日志。
规划复现
failtrace plan 会算出如何在本地复现失败的作业,并打印计划。它目前还不会执行任何操作。
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 作业的真实输出(已删减):
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中,请完全按写法使用它们:它们会在任何内容运行之前填入真实值。不要要求验证它们,也不要用示例替换它们。
FailTrace – 从 URL 在本地复现失败的 GitHub Actions 运行
复现计划 · pytest-dev/pytest
Job build (ubuntu-py311) (jobs.build)
Verdict PARTIAL: 可以运行,但下面的警告可能使其与 CI 不同
Image ubuntu:26.04 linux/amd64
匹配 runner 镜像 ubuntu-26.04 20261111.196.1
Commit c484767
工具链
python 3.11.18 精确 · 要求 "3.11" · 来自 actions/setup-python@6d4fd22
uv 0.13.8 精确 · 来自 astral-sh/setup-uv@11f9893
步骤
1 checkout Run actions/checkout@3d3c42e
pytest-dev/pytest @ c484767 (merge of 58b8dae into 50234b4)
2 skip Download Package
— 从另一个 job 下载 artifacts
3 toolchain 设置 Python 3.11
→ 安装 python 3.11.18
4 composite Run pytest-dev/pytest/.github/actions/setup-tox@c484767
— 复合 action;其内部步骤见下
5 toolchain Run astral-sh/setup-uv@11f9893
→ 安装 uv 0.13.8
6 run $ if [ -n "$PYTHON_VERSION" ]; then (+4 lines)
7 run Test with coverage ← 在 CI 中失败
$ tox run -e py311-coverage --installpkg `find dist/*.tar.gz`
shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
问题
! [step 2] actions/download-artifact@9000827 下载由另一个 job 或 run 产出的 artifacts;它提供的文件在本地会缺失
i [step 1] CI 测试的是将 PR head 58b8dae 合并到 base 50234b4 的结果(合并提交 c484767),而非仅 PR 分支;该计划检出的是这个合并提交
计划的构建方式:
- 日志是实际运行内容的权威来源。脚本、shell 和环境来自 GitHub 打印的步骤头部,因此 ${{ matrix.* }} 及其他表达式已经填充完毕。复合 action 会显示其内部步骤。
- CI 测试的确切提交。对于 pull request,那是 GitHub 创建的合并提交,而不是你的分支 head。这是失败“在本地不发生”的常见原因。
- 确切的工具链版本。workflow 中的 "3.11" 会变成 3.11.18,从 runner 的工具缓存路径读取。当日志不显示版本时,它会读取版本文件,例如 go.mod(包括 toolchain)、.nvmrc、.python-version、.tool-versions 以及 package.json 中的 packageManager。
- 正确的 base 镜像。如果 job 指定了容器,则按原样使用。否则它会选择与 job 实际获得的 runner 镜像相匹配的 Ubuntu 版本。
- 跳过与标记的内容。缓存、上传和覆盖率报告器会被跳过。下载的 artifacts、service 容器、secrets、未知 actions,以及未经过 setup 步骤使用的工具(它们在 runner 上是预装的)都会被报告为问题。
判定结果分为 ready(没有已知缺失)、partial(可以运行,但部分内容被近似处理或缺失)或 blocked(失败的步骤是一个 action 而不是脚本,因此尚无法重放)。
支持的 setup actions:actions/setup-go、setup-node、setup-python、setup-java、setup-dotnet、ruby/setup-ruby、dtolnay/rust-toolchain、actions-rust-lang/setup-rust-toolchain、pnpm/action-setup、pnpm/setup、astral-sh/setup-uv、oven-sh/setup-bun 和 denoland/setup-deno。
复现失败
failtrace repro 会构建计划并在 Docker 中运行它,然后将结果与 CI 的失败进行比较。
failtrace repro <run-url>
failtrace repro --keep <run-url> # 保留容器以便之后查看
API_TOKEN=... failtrace repro --secret API_TOKEN <run-url>
failtrace repro --toolchain node=20.11.1 <run-url> # 填充或覆盖某个工具链
failtrace repro --platform linux/arm64 <run-url> # 在 Apple silicon 上原生运行(更快,但不那么精确)
failtrace repro --runs 10 <run-url> # 是不是偶发失败?
failtrace repro --shell <run-url> # 之后在容器内调试
failtrace repro --report repro.md <run-url> # 为 issue 或 PR 生成 Markdown 报告
文章标题:FailTrace – 从 URL 在本地复现失败的 GitHub Actions 运行
正文: 你需要 Docker(Docker Desktop、colima、OrbStack 等)和 git。
一次失败的 stretchr/testify 运行的真实输出,其中 go vet 在 Go oldstable 下失败。FailTrace 将 oldstable 解析为 CI 使用的确切 Go 1.26.9 构建,检出 CI 测试的 PR 合并提交,并重放了这些步骤:
$ failtrace repro --platform linux/arm64 https://github.com/stretchr/testify/actions/runs/39247781971
Reproducing stretchr/testify · build (oldstable) · plan ready
▶ Image failtrace-env:08414601e6c4aef4 (cached)
▶ Workspace stretchr/testify @ 9272105
▶ [3/5] Run ./.ci.gogenerate.sh
✓ exit code 0 (17.7s)
▶ [4/5] Run ./.ci.gofmt.sh
✓ exit code 0 (7.4s)
▶ [5/5] Run ./.ci.govet.sh ← failed in CI
│ assert/assertion_compare_test.go:85:13: non-constant format string in call to (*testing.common).Errorf
│ assert/assertion_compare_test.go:94:13: non-constant format string in call to (*testing.common).Errorf
✗ exit code 1 (10.7s)
✓ Reproduced: the step fails locally the same way it failed in CI
• the same error: assert/assertion_compare_test.go:<n>:<n>: non-constant format string in call to (*testing.common).Errorf
CI Local
Exit code 1 1
Failure lint / format check lint / format check
Steps 4 passed · 1 failed (39s total)
Image failtrace-env:08414601e6c4aef4 linux/arm64
Differences from CI
- the image is plain ubuntu:24.04 with common runner packages; GitHub's runner image has far more preinstalled
- steps run as root; on GitHub's runners they run as the `runner` user with passwordless sudo
- running linux/arm64, but CI ran linux/amd64
不加 --platform 时,作业会像 CI 那样以 linux/amd64 运行。在 Apple silicon Mac 上这意味着模拟:同样的复现耗时约 9 分钟而不是 40 秒,结论相同。
发生了什么:
- 环境镜像。计划的基础镜像,加上每个 GitHub Ubuntu runner 都有的软件包(git、curl、构建工具、python3、jq、sudo 等),再加上工具链。Go、Node 和 Python 与 setup-go、setup-node 和 setup-python 下载的构建相同,安装在 CI 存放它们的 /opt/hostedtoolcache 下。uv、pnpm 和 Rust 从其发布版本安装。镜像以其内容的哈希打标签,因此每个环境只构建一次。
- 工作区。CI 测试的确切提交会以 actions/checkout 的方式在你的机器上获取,使用相同的 fetch 深度,并挂载到与 runner 上相同的路径(/home/runner/work/<repo>/<repo>,容器作业则为 /__w/...)。如果 GitHub 此后替换了拉取请求的合并提交,合并会在本地重新创建。
- 服务。服务容器在作业容器的网络命名空间中启动,因此 localhost:5432 和 postgres:5432 都能工作,FailTrace 会等待它们的健康检查。
- 步骤。Run 步骤按 CI 使用的 shell、环境和工作目录依次重放。$GITHUB_ENV 和 $GITHUB_PATH 会在步骤之间传递。失败步骤的输出实时流式显示。
- 结论。reproduced:相同的测试失败,或相同的错误或退出码。different-failure not-reproduced:该步骤在本地通过。diverged:较早的步骤在本地失败,因此失败的步骤从未运行。flaky:使用 --runs 时,该步骤在某些运行中失败但并非全部。每个结论都会附带一份与 CI 的已知差异列表。
- reproduced:相同的测试失败,或相同的错误或退出码。
- different-failure
- not-reproduced:该步骤在本地通过。
- diverged:较早的步骤在本地失败,因此失败的步骤从未运行。
- flaky:使用 --runs 时,该步骤在某些运行中失败但并非全部。
每个结论都会附带一份与 CI 的已知差异列表。
不稳定失败:--runs N
设置步骤只运行一次,随后失败的步骤在同一容器中运行 N 次,因此重复运行的成本很低。如果它只是偶尔失败,判定结果就是不稳定(“该步骤在 10 次运行中失败了 3 次”)。这些运行会绕过 Go 的测试缓存(GOFLAGS=-count=1)。否则 go test 会重放缓存中的通过结果,从而掩盖不稳定性。
在容器内调试:--shell
运行结束后,--shell 会打开一个 shell,位置就是失败步骤运行的地方:相同的目录、环境、工具链和服务。它会打印重新运行该步骤的命令:
▶ Shell inside the container at step 5 (Run ./.ci.govet.sh); type exit to finish
re-run the step with: bash -e /home/runner/work/_temp/failtrace/step-5.sh
如果更早的步骤出现了偏差,shell 会在该步骤处打开。退出时容器会被移除,除非你传入 --keep。
共享结果:--report FILE
--report repro.md 会写入一份 Markdown 报告,可粘贴到 issue 或 pull request 中。报告包含判定结果、CI 与本地对比表、环境、差异、每个步骤的结果,以及失败步骤在两侧的输出。--report - 会打印该报告,而不是终端摘要。参见 docs/example-report.md,它是用 --runs 3 从上面的 stretchr/testify 运行生成的。
安全。repro 会在你机器上的容器中运行仓库的代码,包括来自 pull request 的代码。容器只能看到工作区,无法访问你的主目录或 Docker socket,除非你通过 --secret NAME 传入,否则不会获得任何密钥。该值从你的环境中读取,因此绝不会出现在你的 shell 历史或进程列表中。只复现你愿意执行其代码的运行。
限制。这些限制会被报告出来,而不是被静默忽略:
- 失败步骤如果是 action 而不是脚本,则无法重放(判定为 blocked)。
- Windows 和 macOS 作业只能在 Linux 中近似模拟。
- 步骤以 root 身份运行,而 CI 使用的是 runner 用户。
- runner 镜像中众多预装工具并非全部存在。
- linux/amd64 作业在 ARM 机器上会被模拟运行。
- 其他作业的产物不可用。
路线图
- inspect:从其 URL 诊断一次失败的运行
- plan:将失败的作业转化为本地复现计划:基础镜像、精确 commit、工具链版本、环境、要重放的步骤
- repro:在 Docker 中运行该计划,并将结果与 CI 对比
- Reports:--report 写入一份包含判定结果和与 CI 差异的 Markdown 报告
- Flaky detection:--runs N 重复运行失败步骤并报告不稳定
- --shell:在失败步骤处进入容器
- Releases:适用于 macOS、Linux 和 Windows 的预编译二进制文件,以及校验和验证的安装脚本
- Homebrew 和 gh 扩展:brew install 和 gh failtrace <run-url>
- Replaying common actions:将 golangci-lint-action 等 action 翻译为它们所运行的命令,从而也能复现其中的失败
开发
go test ./... # unit tests (no network or Docker needed)
go test -race ./...
go vet ./...
go test -tags integration ./internal/repro/ # runs real containers; needs Docker
goreleaser release --snapshot --clean # build release archives locally, publish nothing
CI 会在每个 pull request 上运行上述所有内容。要发布版本,请推送一个版本标签(git tag v0.1.0 && git push origin v0.1.0);release.yml 会构建并上传二进制文件。
项目布局:
cmd/failtrace/ CLI 入口点
internal/cli/ 命令与标志
internal/runurl/ 运行 URL 的解析与校验
internal/github/ 精简的 GitHub REST 客户端与 token 查找
internal/joblog/ 作业日志解析、失败提取与分类
internal/workflow/ workflow YAML 解析、job/step/matrix 匹配
internal/inspect/ 把以上各部分整合成一份报告
internal/plan/ 构建复现计划(镜像、commit、工具链、环境变量、步骤)
internal/toolchain/ 将工具链解析为 setup-* actions 使用的构建版本
internal/docker/ 通过 docker CLI 运行容器
internal/repro/ 执行计划并将结果与 CI 对比
internal/report/ 终端渲染
贡献
欢迎提交 issue 和 pull request。目前最有用的贡献:
- FailTrace 处理错误的失败运行。请提交 issue,附上运行 URL 以及你期望的结果。
- 新的失败特征:尚未被检测到的测试运行器、包管理器和编译器。这些位于 internal/joblog/analyze.go,并且需要配一个测试用例。
- 更多已知 action:setup actions(internal/plan/toolchains.go),以及可以安全地在本地跳过的 actions(internal/plan/actions.go)。每项都只是一条表项。