FailTrace 发布:在本地复现 GitHub Actions 失败任务

Mores的头像Mores
FailTrace 发布:在本地复现 GitHub Actions 失败任务

开发者 Ri4dH 发布了命令行工具 FailTrace,用于追踪失败的 GitHub Actions 运行并在本地机器上复现。使用者粘贴一条失败运行的链接,工具会识别出失败的作业、失败的步骤、确切的提交以及失败原因。

该项目目前处于早期开发阶段,提供 inspect、plan 和 repro 三个可用命令,以 MIT 许可证分发,支持 macOS、Linux 和 Windows 的预编译二进制文件。

从失败链接出发

FailTrace 的起点是一条失败运行的链接,而不是工作流文件。这与开发者常用的 act 不同:act 从工作流文件出发在本地运行 Actions,FailTrace 则从一次已经失败的运行出发,先定位问题再谈复现。工具会报告该次运行对应的确切提交、尝试次数、作业、矩阵组合以及失败的步骤。

inspect 命令可以接受运行链接、作业链接或某次尝试的链接。它把失败的作业映射回工作流定义,包括矩阵作业名,并还原矩阵取值。报告内容涵盖运行上下文、runner 信息、失败步骤的定义以及在 CI 中实际执行的命令。

针对长日志把首个错误埋在大量输出之后的问题,FailTrace 的做法是从日志中提取失败信息,并展示本地复现所需的上下文。在 prometheus/prometheus 的一次失败运行中,工具把日志摘录聚焦到一处修改了 go.mod 的 go mod tidy 变更,并将原因标记为生成文件差异,退出码为 2。

诊断与复现计划

FailTrace 依据具体信号对失败进行分类,类别包括测试失败、构建错误、依赖问题、lint 失败、生成文件差异、超时和内存不足退出。工具还会标出使复现变复杂的条件,例如服务容器、作业容器、密钥、可复用工作流以及 macOS 或 Windows runner。

plan 命令只计算复现计划并打印出来,不运行容器。它把 GitHub Actions 日志作为脚本、shell 和环境值的权威来源,工作流表达式会解析为 CI 当时使用的取值。对于拉取请求运行,计划会识别 GitHub 实际测试的合并提交。

工具链解析让计划更精确。当日志中出现 runner 工具缓存路径时,FailTrace 会把 Python 3.11 这类请求版本解析为 CI 使用的确切构建版本。它还会读取 go.mod、.nvmrc、.python-version、.tool-versions 以及 package.json 中的 packageManager 等版本文件。基础镜像来自作业容器,或来自与 runner 镜像匹配的 Ubuntu 版本。支持的 setup 动作包括 actions/setup-go、actions/setup-node、actions/setup-python、actions/setup-java、actions/setup-dotnet、ruby/setup-ruby、dtolnay/rust-toolchain、pnpm/action-setup、astral-sh/setup-uv、oven-sh/setup-bun 和 denoland/setup-deno 等。

每个计划都以一个判定收尾。ready 表示没有已知的缺失环节;partial 表示计划可以带着近似或缺失部分运行;blocked 表示失败步骤使用的是 action 而非脚本,重放无法继续。计划会跳过缓存、上传和覆盖率报告,并对下载的产物、服务容器、密钥、未知动作和预装工具报告问题。

在 Docker 中重跑

repro 命令会构建计划、在 Docker 中运行,并把本地结果与 CI 失败进行比对。该命令面向同时具备 Docker 和 Git 的环境。在一次 stretchr/testify 失败运行的重现中,FailTrace 把 oldstable 解析为 CI 使用的确切 Go 1.26.9 构建,检出 CI 测试的合并提交,并报告了相同的 go vet 失败。

FailTrace 从选定的基础镜像构建环境镜像,加入常见 runner 软件包并安装工具链。镜像以其内容的哈希打标签,因此重复运行可以复用镜像。工具获取 CI 测试的确切提交,把工作区挂载到 runner 路径,并按顺序重放步骤。服务容器在作业容器的网络命名空间中运行,FailTrace 在执行步骤前等待健康检查通过。步骤的环境变更通过 $GITHUB ENV 和 $GITHUB PATH 传递。

判定用于描述比对结果。reproduced 表示相同的测试失败,或出现相同的错误与退出码;其他结果包括 different-failure、not-reproduced、diverged 和 flaky。--runs 参数会在同一容器中重复失败步骤以检测不稳定行为,这些重复运行中 FailTrace 会关闭 Go 测试缓存。开发者可以用 --keep 保留容器、用 --shell 打开 shell、用 --secret 传入密钥、用 --toolchain 覆盖工具链、用 --platform 选择平台,并用 --report 写出 Markdown 报告。在 Apple 芯片机器上,--platform linux/arm64 以放弃与 amd64 CI runner 的精确匹配换取更快的执行。

判定结果与安全提示

FailTrace 随命令附带了安全指引。复现过程会在开发者本机的容器内运行仓库代码。该容器无法访问主目录和 Docker socket,密钥只在开发者通过 --secret 提供时才会传入。

这些限制与工具的能力边界相关:复现依赖本地容器环境,而容器本身被刻意收窄了权限范围。工具对无法重放的情况会作出报告,包括失败的 action 步骤、在 Linux 中近似处理的 Windows 和 macOS 作业、以 root 执行、在 ARM 机器上模拟 amd64,以及其他作业产生的产物。

适用范围与后续计划

FailTrace 目前覆盖失败步骤使用 run:脚本的 Linux 作业。

安装方式包括:macOS 和 Linux 可通过安装脚本下载最新发布并校验 SHA-256 校验和;发布页面提供 macOS、Linux 和 Windows 上 amd64 与 arm64 的预编译二进制文件以及 checksums.txt;Go 用户可以用 go install github.com/Ri4dH/failtrace/cmd/failtrace@latest 安装。

使用日志 API 需要 GitHub token,即使是公开仓库也一样。工具会读取 GITHUB TOKEN、GH TOKEN,或从 gh auth token 获取令牌。私有仓库需要具备读取 Actions 权限的令牌,GitHub Enterprise Server 的链接可通过 host API base 使用。开发者可以用 --job 把输出限制到单个作业,用 -n 控制日志上下文,用 --json 为脚本输出 JSON。

Ri4dH 的路线图把检查、计划、复现、Markdown 报告、不稳定检测、shell 访问和发布二进制文件标为已完成。计划中的工作包括 Homebrew 打包、gh failtrace 扩展,以及对 golangci-lint-action 等常见 action 的重放支持。

要点

  • FailTrace 提供 inspect、plan、repro 三个命令
  • 工具需 GitHub token 才能读取日志 API
  • 复现仅覆盖失败步骤使用 run 脚本的 Linux 作业
  • 项目以 MIT 许可证分发

原文链接

更多快讯

全部快讯
  1. Hydra Host 将开源 Hydra OS,面向 AI 工厂运营
  2. Fwupd 2.1.10 发布:新增 Synaptics 96F1 触控板固件支持
  3. CleanYourTV 3.5.0 发布:主页内存降至 114MB,支持472款电视
  4. Plannotator 24小时新增860星,登上 GitHub Trending
  5. DeepSeek Harness 0.2.2 候选版发布,可把任务交给 Codex 与 Claude

0 条回复

A文章作者M管理员
上传评论图片

暂无讨论,说说你的看法吧