Grafy News
Try Grafy free

FailTrace lets developers replay failed GitHub Actions runs locally

FailTrace, a new open‑source CLI, extracts the exact failing step from a GitHub Actions run and generates a Docker‑based reproduction plan.

Illustration for the news story: FailTrace lets developers replay failed GitHub Actions runs locallySource: Hacker News — front page

What is FailTrace and why it matters?

FailTrace is an early‑stage open‑source tool that helps developers stop guessing why a GitHub Actions workflow failed. By feeding it the URL of a failed run, the utility identifies the exact job, step, and commit that caused the error, then produces a concise diagnosis and a reproducible Docker command. According to the repository README, the goal is to “replay only what the failing step needs, not the whole workflow,” which can dramatically cut the time spent chasing flaky or environment‑specific CI bugs.

How does FailTrace work?

The tool follows a three‑command workflow:

  1. inspect – pulls the run metadata, logs, and workflow file at the exact commit, then highlights the failing step and its error.
  2. plan – builds a local reproduction plan, selecting the runner image, toolchain versions, and environment variables needed to recreate the failure.
  3. repro – launches a Docker container that mirrors the CI environment and runs the failing command.

FailTrace reads the GitHub Actions logs API, which requires a token (looked up from GITHUB_TOKEN, GH_TOKEN, or the GitHub CLI auth token). It then parses step definitions, matrix values, and composite action internals so that expressions like ${{ matrix.tool }} are already resolved.

Which CI failures can it reproduce?

The current implementation focuses on Linux jobs whose failing step is a run: script. It can diagnose a range of failure categories, including test failures, build errors, dependency issues, lint problems, generated diffs, timeouts, and out‑of‑memory exits. The README provides a taxonomy of categories with examples such as:

  • test – --- FAIL: TestX
  • build – error TS2304
  • dependency – npm ERR! code ERESOLVE
  • lint – golangci-lint
  • generated-diff – diff output from go mod tidy
  • timeout – exceeded execution time
  • out-of-memory – exit code 137

If a run fails before any job starts, uses a dynamic workflow without a file in the repo, or the logs have expired, FailTrace reports the edge case instead of silently failing.

How to install and use FailTrace?

FailTrace offers several installation paths:

  • macOS/Linux script – curl -fsSL https://raw.githubusercontent.com/Ri4dH/failtrace/main/scripts/install.sh | sh
  • Go install – go install github.com/Ri4dH/failtrace/cmd/failtrace@latest (requires Go 1.24+)
  • Pre‑built binaries – available for amd64 and arm64 on the releases page.

Typical usage looks like this:

# Show why a run failed
failtrace inspect https://github.com/owner/repo/actions/runs/123456789

# Generate a reproduction plan (no execution yet)
failtrace plan https://github.com/owner/repo/actions/runs/123456789

# Run the failing step in Docker
failtrace repro https://github.com/owner/repo/actions/runs/123456789

Flags such as -n 60 increase log context, while --json emits machine‑readable output for scripting.

Applying FailTrace with Grafy

Grafy’s Code app provides an AI‑enhanced coding studio where you can run CLI tools inside a managed container. To experiment with FailTrace without leaving the Grafy environment, you can:

  1. Open the /code workspace.
  2. Use the integrated terminal to install FailTrace via the script or go install command.
  3. Run failtrace inspect … on a recent failed GitHub Actions URL.
  4. Copy the generated Docker command into a Grafy Code terminal session to see the failure reproduce instantly.

If you prefer a conversational approach, the Chat app can help you interpret the JSON output or suggest adjustments to the reproduction plan. Neither app adds new functionality beyond what FailTrace already offers, but they provide a convenient sandbox for trying the tool and sharing the results with teammates.


Source: https://github.com/Ri4dH/failtrace

To explore this yourself, open Grafy Code: an AI coding studio.

Frequently asked questions

How does FailTrace differ from the existing act tool?

act runs an entire workflow locally, requiring you to configure the job matrix and environment yourself. FailTrace starts from a specific failed run, automatically extracts the exact commit, matrix values, and failing step, and focuses on reproducing just that step.

Can FailTrace reproduce failures on macOS or Windows runners?

At present, the repro command only supports Linux jobs whose failing step is a run: script. macOS and Windows runners are not yet covered, though the tool can still inspect and plan them.

What authentication is needed for private repositories?

FailTrace needs a GitHub token with permission to read Actions logs. It checks GITHUB_TOKEN, then GH_TOKEN, and finally the token provided by the GitHub CLI (gh auth token). For Enterprise Server instances, the API base URL is adjusted accordingly.


Source: Hacker News — front page — FailTrace – Reproduce a failed GitHub Actions run locally from its URL