Technology1 min read

FailTrace – Reproduce a failed GitHub Actions run locally from its URL

By · Published by Everything Blog

In short

The tool currently provides three core operational commands labeled inspect, plan, and repro to diagnose issues, draft execution strategies, and run the failed script locally. It focuses exclusively on the failing step rather than replaying entire sequences, filtering noise by anchoring log outputs to the initial error line. For execution, it utilizes Docker to run Linux-based tasks that rely on standard run scripts. The application can output its diagnostic reports in either plain text or structured JSON.

Key points

  • Users need to provide a GitHub personal access token to inspect runs even when querying p…: Users need to provide a GitHub personal access token to inspect runs even when querying public repositories.
  • The utility provides dedicated inspect, plan, and repro commands to diagnose, outline, an…: The utility provides dedicated inspect, plan, and repro commands to diagnose, outline, and locally execute failed workflow steps.
  • Prebuilt binaries are available across amd64 and arm64 architectures for Windows, macOS,…: Prebuilt binaries are available across amd64 and arm64 architectures for Windows, macOS, and Linux, with compilation requiring Go 1.24 or newer.

Sources checked by our analysis pipeline: 1

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 arun:

script. See the roadmap and limitations.

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…

Technology