返回资讯中心
外部精选
软件工程
#社区热议

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 定位不同,专注回答这次运行为何失败、能否在本地复现。

Hacker Newsri4dh2026/11/19 · 今天30 分钟阅读

以下正文由 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 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →