Newshot

FailTrace – 从 URL 在本地复现失败的 GitHub Actions 运行

Translation(model translation, not the source's own text)

FailTrace

Latest release
Latest release

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

FailTrace reproducing a failed stretchr/testify CI run in Docker
FailTrace reproducing a failed stretchr/testify CI run in Docker

粘贴一个失败的 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, --lines25显示失败步骤的日志行数
--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
builderror TS2304 , undefined: foo , error[E0425]
dependencynpm ERR! code ERESOLVE , missing go.sum entry
lintgolangci-lint , eslint , ruff steps
generated-diffa check that printed diff --git (tidy, codegen, formatters)
timeoutexceeded the maximum execution time
out-of-memoryexit 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)。每项都只是一条表项。

许可证

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Hacker News
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗