ci-fix-brief

Turn noisy CI logs into compact repair briefs for coding agents.

ci-fix-brief reads a failing CI log and extracts the commands, test summaries, high-signal failure lines, nearby context, and next repair steps. It runs locally, has zero runtime dependencies, and redacts common token shapes before printing output.

Problem

Failed CI logs are often long, repetitive, and awkward to paste into a coding-agent session. The useful facts are usually scattered across commands, test summaries, stack traces, and the final exit line.

Why This Exists

Coding agents fix CI faster when they get a small, structured failure brief instead of a raw log dump. ci-fix-brief gives maintainers a deterministic first pass that is safe to inspect, easy to paste, and usable in scripts.

Installation

From this repository:

python -m pip install .

After publishing:

pipx install git+https://github.com/itscloud0/ci-fix-brief.git

30-Second Quickstart

python -m pip install .
ci-fix-brief examples/failing-pytest.log

Save a Markdown repair brief:

ci-fix-brief examples/failing-pytest.log --output ci-brief.md

Emit JSON for automation:

ci-fix-brief examples/failing-pytest.log --format json

Pipe a log from another command:

cat examples/npm-build.log | ci-fix-brief --format json

Demo Output

# CI Fix Brief

Source: `examples/failing-pytest.log`

## Snapshot

- Lines scanned: 13
- Findings: 2
- Commands detected: 1

## Likely Failing Commands

- `pytest`

## Test Summary

- 1 failed, 12 passed in 0.48s

## Findings

### 1. tests/test_api.py::test_healthcheck - AssertionError: expected 200

- Severity: `error`
- Category: `test`
- Line: `9`

Usage Examples

Generate a brief from a GitHub Actions log saved to disk:

ci-fix-brief failed-run.log --output CI_FIX_BRIEF.md

Use a stricter context window:

ci-fix-brief failed-run.log --context 4 --max-findings 12

Make a CI job fail when the log contains high-signal failures:

ci-fix-brief failed-run.log --fail-on-findings

Use JSON in another script:

ci-fix-brief failed-run.log --format json | python -m json.tool

Common Use Cases

• Paste a compact CI failure brief into a coding-agent repair prompt.
• Summarize failed GitHub Actions logs before opening an issue.
• Store CI_FIX_BRIEF.md as a lightweight artifact after a failed run.
• Convert raw test logs into JSON for internal automation.
• Reduce accidental token exposure when sharing logs by redacting common token shapes.

Comparison And Alternatives

• Raw CI logs preserve everything, but they are noisy and expensive to review.
• grep is fast, but it does not group commands, context, summaries, and repair steps.
• Full observability tools are deeper, but they require services and setup. This tool is local-first and small.
• Secret scanners are stricter. ci-fix-brief only redacts common token shapes in rendered output.

Limitations

• Detection is heuristic and focused on common CI/test log shapes.
• It does not download logs from GitHub; save or pipe logs into the CLI.
• Redaction is best-effort and not a replacement for secret scanning.
• Very large logs should be pre-trimmed to the failed job or failing step.
• Python 3.9+ is required.

Roadmap

• Add a gh run view helper mode that shells out to GitHub CLI when available.
• Add pattern fixtures for Go, Rust, Java, and Playwright failures.
• Add SARIF-like JSON output for downstream tools.
• Add a GitHub Action wrapper that uploads the brief as an artifact.

Contributing

See CONTRIBUTING.md. Small fixtures for real-world CI failure formats are especially useful.

License

MIT. See LICENSE.