返回资讯中心
外部精选
软件工程
#开发者实时流

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 不同,聚焦于回答某次运行为何失败及如何本地复现。

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

打开原文
去社区讨论 →