· via Hacker News – Front Page (native)
FailTrace turns a failed GitHub Actions run URL into a local reproduction
FailTrace takes the URL of a failed GitHub Actions run, pinpoints the failing job and step, categorises the error, and can plan or execute a local Docker reproduction.
A tool that starts from the failure
Debugging a red GitHub Actions run usually means a browser tab, a long log and a lot of scrolling. FailTrace, an open-source command-line tool published on GitHub by Ri4dH and currently on the Hacker News front page, takes a different starting point: you paste the URL of a failed run, and it works backwards from there.
According to the project's README, the tool locates the job and step that failed, matches them to the workflow file as it existed at the exact commit that ran, extracts the failure from the logs, and reports what stands between you and reproducing it on your own machine.
Three commands, one URL
Everything is driven by the run URL and organised around three verbs. failtrace inspect explains why a run failed. failtrace plan works out how the failed job could be reproduced locally and prints the plan without executing anything. failtrace repro carries out the reproduction in Docker.
The project describes itself as being in early development: all three commands work, but reproduction currently covers Linux jobs whose failing step is a plain run: script. Steps that invoke marketplace actions are not replayed.
What inspect reports
Inspect is the triage layer. For each failed job it reports the run context — workflow, event, branch, commit and attempt — maps the job back to its definition in the workflow file, reconstructing matrix values for jobs with templated names, and identifies both the requested runner label and the actual runner image and version.
The failed step is shown with its definition and with the command as printed in the log, expressions already resolved. A diagnosis layer then combines the exit code, error annotations and failing test names from a range of ecosystems — Go, pytest, Jest, Vitest, Cargo and RSpec — and assigns the failure a category: test, build, dependency, lint, generated-diff, timeout or out-of-memory.
A worked example in the README uses a failed prometheus/prometheus run whose log ends in hundreds of lines of go.sum diff. FailTrace centres its excerpt on the first error line, so the actual cause — go mod tidy modifying go.mod — is visible instead of buried under trailing noise. The diagnosis reads: files out of date, exit code 2.
Inspect also surfaces anything that complicates local reproduction: service containers, job containers, secrets the step uses, reusable workflows, and macOS or Windows runners. Edge cases are explained rather than failing silently, including runs that failed before any job started, dynamic workflows with no file in the repository, and expired logs.
Plan before you run
failtrace plan stops short of executing anything. Sample output for a failed pytest-dev/pytest job shows the approach: it selects an Ubuntu image matching the runner image, resolves the exact Python version behind a loose "3.11" specification, expands a composite action into its steps, notes that artifact downloads from another job are skipped, and marks the step that failed in CI. The verdict in that example is "PARTIAL" — the plan can run, but warnings mean it may behave differently from CI. On the roadmap are final verdicts of reproduced, not reproduced or flaky, along with a report of what differed between CI and the local machine.
The relationship with act
The obvious comparison is act, which runs workflows locally from a workflow file. FailTrace frames the two as complementary rather than competing. Act executes a whole workflow that you configure; FailTrace starts from a specific failure — a known commit, attempt, job, matrix combination and step — and aims to replay only what the failing step needs.
Installation and authentication
The tool ships as prebuilt binaries for macOS, Linux and Windows on amd64 and arm64, an install script for macOS and Linux that verifies a SHA-256 checksum, and go install for anyone running Go 1.24 or newer.
A GitHub token is required even for public repositories, because the logs API demands one. FailTrace checks GITHUB_TOKEN, then GH_TOKEN, then falls back to gh auth token from the GitHub CLI. Private repositories need a token with Actions read access, and GitHub Enterprise Server installations are supported.
Why it matters
CI failures are still, for most teams, debugged by reading logs in a browser — and flaky or environment-specific failures are the worst cases, because the evidence is scattered and sometimes expires. A tool that turns a run URL into a categorised diagnosis, a reproduction plan and, eventually, a local replay attacks that workflow directly. Starting from the failure rather than the whole workflow is a genuinely different model, and even in its current early state, the inspect and plan commands alone look capable of cutting real time off CI triage.
- #github-actions
- #ci-cd
- #open-source
- #developer-tools
- #docker