GitHub - Ri4dH/failtrace: Stop guessing why CI failed. Reproduce it locally.
Pangram verdict · v3.3
We believe that this text is a mix of AI and human-written content.
AI likelihood · overall
AIArticle text · 1,213 words · 12 segments analyzed
Stop guessing why CI failed.
Reproduce it locally. Paste a failed GitHub Actions run URL. FailTrace finds the job and step that failed, matches them to the workflow file at that exact commit, pulls the failure out of the logs, and tells you what stands between you and reproducing it on your machine. 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 Status: early development.
All three commands work.
repro covers Linux jobs whose failing step is a run: script. See the roadmap and limitations.
Why not act?
act runs your workflows locally, and it's great at that. FailTrace answers a different question: why did this particular run fail, and can I make it fail the same way here? It starts from a failed run, not a workflow file. You get the exact commit, attempt, job, matrix combination, and failing step.
Nothing to configure.
It focuses on the failure. The goal is to replay only what the failing step needs, not the whole workflow. It gives you a verdict. You get a diagnosis now. Later you'll also get reproduced / not reproduced / flaky, plus what differed between CI and your machine.
Example Real output for a failed prometheus/prometheus run (trimmed): ✗ 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 The log ends with hundreds of lines of go.sum diff.
FailTrace centres the excerpt on the first error line so you see the cause, go mod tidy changing go.mod, instead of the noise after it. Install macOS and Linux, using the install script. It downloads the latest release for your platform and verifies its SHA-256 checksum: curl -fsSL https://raw.githubusercontent.com/Ri4dH/failtrace/main/scripts/install.sh | sh It installs to /usr/local/bin if that's writable, otherwise to ~/.local/bin. Set FAILTRACE_INSTALL_DIR to choose, or FAILTRACE_VERSION=v0.1.0 to pin a release. Prebuilt binaries for macOS, Linux and Windows (amd64 and arm64) are on the releases page, with a checksums.txt. With Go 1.24+: go install github.com/Ri4dH/failtrace/cmd/failtrace@latest From source: git clone https://github.com/Ri4dH/failtrace cd failtrace go build -o bin/failtrace ./cmd/failtrace Usage # 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 Print the report as JSON -n, --lines 25 Log lines to show from the failed step --job all failed Inspect only this job ID Colour output turns off automatically when stdout is not a terminal, or when NO_COLOR is set. Authentication FailTrace needs a GitHub token, even for public repositories, because the logs API requires one. It looks in this order: GITHUB_TOKEN GH_TOKEN gh auth token (if you use the GitHub CLI, this already works) Private repositories need a token that can read Actions on that repo. GitHub Enterprise Server URLs work too: the API base becomes https://<host>/api/v3. What inspect reports Run context: workflow, event, branch, commit, attempt. Job → workflow mapping: finds the job definition, including jobs named like test (ubuntu-latest, 1.22) or Lint ${{ matrix.tool }}, and recovers the matrix values. Runner: the requested label and the actual runner image and version, from the log. Failed step: its definition (run, uses, with, env, shell, working directory). The command shown is the one printed in the log, with expressions already filled in. Diagnosis: exit code, error annotations, failing test names (Go, pytest, Jest, Vitest, Cargo, RSpec), and a category: Category Example signal 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 Reproduction notes: anything that makes a local repro harder. That means service containers, job containers, secrets the step uses, reusable workflows, and macOS or Windows runners. It also explains edge cases instead of failing silently: runs that failed before any job started, dynamic workflows with no file in the repo, and logs that have expired. Planning a reproduction failtrace plan works out how to reproduce the failed job locally and prints the plan. It doesn't run anything yet. 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 Real output for a failed pytest-dev/pytest job (trimmed): 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 1 checkout Run actions/checkout@3d3c42e pytest-dev/pytest @ c484767 (merge of 58b8dae into 50234b4) 2 skip Download Package — downloads artifacts from another job 3 toolchain Set up Python 3.11 → install python 3.11.18 4 composite Run pytest-dev/pytest/.github/actions/setup-tox@c484767 — composite action; its steps follow 5 toolchain Run astral-sh/setup-uv@11f9893 → install uv 0.13.8 6 run $ if [ -n "$PYTHON_VERSION" ]; then (+4 lines) 7 run Test with coverage ← failed in CI $ tox run -e py311-coverage --installpkg `find dist/*.tar.gz` shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0} Issues ! [step 2] actions/download-artifact@9000827 downloads artifacts produced by another job or run; files it provides will be missing locally i [step 1] CI tested the merge of PR head 58b8dae into base 50234b4 (merge commit c484767), not the PR branch alone; the plan checks out that merge commit How the plan is built: The log is the source of truth for what ran. Scripts, shells and environment come from the step headers GitHub prints, so ${{ matrix.* }} and other expressions are already filled in. Composite actions show their inner steps. The exact commit CI tested. For pull requests that's a merge commit GitHub created, not your branch head. This is a common reason a failure "doesn't happen locally". The exact toolchain versions. "3.11" in the workflow becomes 3.11.18, read from the runner's tool cache paths. When the log doesn't show a version, it reads version files such as go.mod (including toolchain), .nvmrc, .python-version, .tool-versions and packageManager in package.json.
The right base image.