gha-repro-kit

gha-repro-kit is a CLI and GitHub Action that turns failed GitHub Actions logs into a compact maintainer handoff.

It is for small open source maintainers, contributors, and agents that need to understand CI-only failures without reading the full raw log.

It takes:

• a local failed GitHub Actions log file
• a public GitHub Actions run ID
• a specific failed job ID from a large workflow

It produces:

• report.md: failing job, step, command, environment hints, and log context
• summary.md: a short PR/issue-ready maintainer summary
• repro.sh: a local reproduction scaffold when a command can be inferred
• analysis.json: machine-readable failure data for agents and follow-up tools
• stdout JSON with --json --no-files for agent workflows

Fast path for agents:

gha-repro-kit --log-file ./failed.log --json --no-files

Project status: early MVP, deterministic parser, public real-world examples included.

Non-goals:

• It does not replace CI, test runners, or code review bots.
• It does not require AI or API access for the MVP.
• It does not execute generated reproduction commands automatically.

The first version intentionally stays narrow: it focuses on failed GitHub Actions runs and produces artifacts maintainers can paste into a PR or issue.

Why this exists

For many small OSS projects, the expensive part of reviewing a contributor PR is not the code diff. It is the CI-only failure:

• the log is long
• the failing matrix entry is easy to miss
• the actual command is buried above the failure
• the contributor needs clear reproduction steps

gha-repro-kit makes that handoff cheaper.

The goal is not to replace CI, test runners, or code review bots. The goal is to give maintainers a compact failure packet they can act on in minutes:

1. what failed
2. which command likely failed
3. what context matters
4. what to run locally

That makes it useful even before any AI integration is configured.

Install

npm install -g gha-repro-kit

For local development:

npm install
npm link

Usage

Analyze an existing failed log:

gha-repro-kit --log-file ./failed.log --out ./repro

Return machine-readable JSON without writing files:

gha-repro-kit --log-file ./failed.log --json --no-files

Analyze a GitHub Actions run with the GitHub CLI:

gha-repro-kit owner/repo --run 123456789 --out ./repro

For large workflows, GitHub CLI may refuse to fetch all failed job logs at once. List failed jobs and pass a specific job ID:

gh run view 123456789 --repo owner/repo --json jobs \
  --jq '.jobs[] | select(.conclusion == "failure") | [.databaseId, .name] | @tsv'

gha-repro-kit owner/repo --run 123456789 --job 987654321 --out ./repro

You can also use a job ID directly:

gha-repro-kit --repo owner/repo --job 987654321 --out ./repro

Or pass the run URL:

gha-repro-kit https://github.com/owner/repo/actions/runs/123456789

The GitHub run mode uses:

gh run view <run-id> --repo <owner/repo> --log-failed

If that fails, authenticate with gh auth login or download the log and use --log-file.

Agent-friendly options:

• --json: print { schemaVersion, analysis, artifacts } as JSON
• --format json: same as --json
• --no-files: skip artifact writes and return artifacts: null
• --quiet: suppress human-readable status lines in text mode

AI-readable metadata:

• llms.txt: concise project context for language models
• agent-card.json: structured capability metadata for agents
• docs/agent-integration.md: current agent contract and future protocol-readiness notes
• docs/analysis-json.md: analysis.json field guide

Try It On A Failed Run

From a repository with a failed GitHub Actions run:

gh run list --repo owner/repo --status failure --limit 5
gha-repro-kit owner/repo --run 123456789 --out ./gha-repro-output
less ./gha-repro-output/report.md

For very large workflows, pick one failed job first:

gh run view 123456789 --repo owner/repo --json jobs \
  --jq '.jobs[] | select(.conclusion == "failure") | [.databaseId, .name] | @tsv'

gha-repro-kit owner/repo --run 123456789 --job 987654321 --out ./gha-repro-output

GitHub Action

Use the action to generate a reproduction packet for the current run:

name: CI failure packet

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  packet:
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: owner/gha-repro-kit@v0
        with:
          repo: ${{ github.repository }}
          run-id: ${{ github.event.workflow_run.id }}
          out: gha-repro-output
      - uses: actions/upload-artifact@v4
        with:
          name: gha-repro-output
          path: gha-repro-output/

Example output

Wrote /repo/repro/report.md
Wrote /repo/repro/repro.sh

report.md includes:

Primary job: test
Primary step: Run tests
Failure: packages/parser/tokenize.test.ts
Likely command: pnpm test packages/parser
Runner: ubuntu
Language versions: node 20.19.0

summary.md is intentionally short enough to paste into a PR discussion.

Failure classes

The parser includes a small set of maintainer-focused classifiers:

• GitHub Action setup step failures, such as actions/setup-python requesting a version that is unavailable on the runner. These are marked as having no direct local reproduction command.
• Download/archive extraction failures, such as curl followed by tar or gzip: stdin: not in gzip format. Reports suggest checking redirects, authentication, rate limits, and the downloaded file contents.
• Native extension build failures involving tools such as maturin, cargo, rustc, or PyO3. Reports point maintainers toward Python/Rust toolchain and dependency checks.

Real-world evidence

The examples/ directory contains generated packets from public failed GitHub Actions runs across Node, Python, and Rust projects. Each example includes a short notes.md describing what the tool got right, what it missed, and the next parser improvement.

Current examples include:

• openai/openai-node: pnpm dependency metadata failure
• BurntSushi/ripgrep: downloaded archive was not gzip
• psf/black: unavailable Python prerelease in actions/setup-python
• pydantic/pydantic: native Rust/Python extension build failure in a large workflow, analyzed with --job

Roadmap

• Generate a Dockerfile or devcontainer when CI setup is inferable
• Add explicit confidence fields to the JSON contract
• Compare failed runs against previous successful runs
• Comment summary.md on failed PR checks
• Detect flaky failures by comparing repeated failed runs
• Add a hosted analysis API only after the CLI/JSON contract has real usage
• Explore x402, ERC-8004, ERC-8126, and ERC-8183 integrations after the hosted agent surface is justified
• Optional OpenAI-powered log summarization and contributor-facing replies

Maintainer impact

This project is designed for public OSS repositories where maintainers review external PRs in limited spare time. The intended success metric is simple:

Can a maintainer understand and reproduce a CI-only failure without reading the full raw log?

If the answer is yes, the contributor gets a clearer reply and the maintainer gets some time back.

gha-repro-kit is especially aimed at small maintainers who do not have a dedicated CI/release engineering team. The tool keeps the raw log available, but turns it into a compact handoff that can be pasted into an issue, PR comment, or maintainer note.

Project status

This is an early MVP. The CLI works best on logs emitted by:

gh run view <run-id> --log-failed

Issues and PRs that include real failed logs are especially useful.