PatchRail

PatchRail is a local-first maintainer automation toolkit for open-source projects. The first public release focuses on CI failure triage: it reads failed CI logs, classifies the likely root cause, extracts evidence signals, and emits Markdown, JSON, or plain text reports that maintainers can review.

PatchRail does not auto-submit pull requests, claim funded issues, or comment on third-party repositories. It produces evidence and reviewable suggestions so maintainers stay in control.

Quickstart

10-second reviewer demo

No install is required to inspect the current behavior. The versioned demo at examples/ci-triage/demo-output.md is real CLI output from the bundled examples/ci-triage/dependency-failure.log fixture, and tests compare that file against the command output to prevent drift. For a single local reviewer smoke test from a source checkout, run:

uv run --extra dev python scripts/reviewer_quick_check.py
uv run --extra dev patchrail evidence reviewer-packet --out-dir patchrail-reviewer-packet

PyPI publishing is pending, so do not use pipx install patchrail yet. Until the package is on PyPI, run the public GitHub source directly:

uvx --from git+https://github.com/patchrail/patchrail patchrail --help
printf 'python -m pytest -q\nFAILED tests/test_app.py::test_ok - AssertionError\n' \
  | uvx --from git+https://github.com/patchrail/patchrail patchrail ci explain

That pre-PyPI smoke test prints:

# PatchRail CI Report

- Root cause: `python_test_failure`
- Confidence: `0.89`
- Subsystem: Python tests
- Reproduce: `python -m pytest -q`
- Suggested action: Reproduce the failing test, patch the narrow behavior drift, and rerun the focused pytest node before broad test runs.

## Evidence signals

- `\bpytest\b`
- `FAILED .*::`
- `AssertionError`

## Safety

PatchRail classified this log locally. It did not create a pull request, post a comment, claim funding, or send data to an external service.

Or install the v0.1.0 release wheel directly from GitHub Releases:

python -m pip install https://github.com/patchrail/patchrail/releases/download/v0.1.0/patchrail-0.1.0-py3-none-any.whl
patchrail --help

After installation, run the local safety check and classify a failed CI log:

patchrail doctor
patchrail ci explain --log failed-github-actions.log

From a source checkout, use the bundled fixture:

uv run --extra dev patchrail doctor
uv run --extra dev patchrail ci explain --log examples/ci-triage/dependency-failure.log

The same versioned demo can be regenerated locally with:

uv run --extra dev patchrail ci explain --log examples/ci-triage/dependency-failure.log --format markdown

Example output:

# PatchRail CI Report

- Root cause: `python_dependency_resolution`
- Confidence: `0.89`
- Subsystem: Python dependency installation
- Reproduce: `python -m pip install -r requirements.txt`
- Suggested action: Pin or relax the conflicting dependency range, then rerun
  the same install command and the affected tests.

Why maintainers use PatchRail

• Turn long CI logs into concise root-cause reports.
• Keep CI log processing local by default.
• Emit Markdown for humans and JSON for automation.
• Preserve a human approval boundary for write actions.
• Use the classifier as a building block for reviewable agent workflows.

Current scope

Area	Status	Notes
CI failure triage	Beta	GitHub Actions-style logs and common OSS toolchains
Markdown/JSON reports	Beta	Suitable for local review or manually pasted reports
Local queue/control plane	Experimental	SQLite-backed work items with human approval states
Funded issue discovery	Planned	Read-only, later, and explicitly anti-abuse

Safety

PatchRail is local-first. The CI classifier does not require billing, a GitHub App, repo write permissions, or an external model call. Write actions are outside the v0.1 scope and must remain human-approved.

Redact logs before sharing fixtures or reports:

uv run --extra dev patchrail doctor --format markdown
uv run --extra dev patchrail redact --log failed.log > failed.redacted.log
uv run --extra dev patchrail ci explain --redact --log failed.log
uv run --extra dev patchrail ci pilot-pack --log failed.log --out-dir patchrail-pilot-pack
uv run --extra dev patchrail ci pilot-summary --pack patchrail-pilot-pack --ci-provider "GitHub Actions" --toolchain Python
uv run --extra dev patchrail schema ci-result > ci-result.schema.json
uv run --extra dev patchrail ci benchmark examples/ci-triage --format markdown

Run the public checks from a fresh checkout:

uv run --extra dev pytest -q
uv run --extra dev ruff check .
uv run --extra dev patchrail ci benchmark examples/ci-triage --format json
uv run --extra dev patchrail evidence snapshot --format markdown
uv run --extra dev patchrail evidence application-gate --format markdown
uv run --extra dev patchrail evidence application-dossier --format markdown
uv run --extra dev patchrail evidence release-readiness --clean-dist --format markdown

See ETHICS.md, SECURITY.md, and docs/threat-model.md.

Documentation

• Quickstart
• CI Janitor
• CI Failure Zoo
• Maintainer pilot guide
• Consent-only pilot request package
• Consent-only pilot outcome example
• Adopters
• Metrics
• GitHub Actions CI triage
• Agent Control Plane
• API reference
• Codex workflows
• Reviewable automation workflows
• Public maintenance workflow ledger
• Agent skills
• Threat model
• Funded issue ethics
• Roadmap
• Release process
• v0.1.0 release evidence
• v0.2.0 release evidence
• v0.3.0 release evidence
• v0.4.0 release evidence
• Codex for Open Source evidence
• Open source evidence tracker

Contributing

The easiest contribution is a sanitized CI failure fixture. See CONTRIBUTING.md and the maintainer pilot guide. If you are not opening a pull request yet, use the CI failure fixture issue template with a redacted log excerpt and the fixture-check result.

If you are testing PatchRail on a repository you maintain, use the adopter report issue template. patchrail ci pilot-pack creates a local redacted pack for that review path. patchrail ci pilot-summary creates a safe outcome snippet and keeps repository names private unless --repository-mention-approved yes is set. Public adopter listings require explicit permission. The consent-only pilot request package has a copyable maintainer checklist and intake rules for pilots that should become public evidence.

When you have multiple reviewed summaries, aggregate them without exposing private repository names:

uv run --extra dev patchrail ci pilot-metrics pilot-summary-*.json --format markdown

To refresh the local evidence view across CI Janitor, the read-only action, Agent Control Plane, Funded Issue Scout, release evidence, and adopter gaps:

uv run --extra dev patchrail evidence snapshot --format markdown

Before drafting an external program application, run the fail-closed gate:

uv run --extra dev patchrail evidence application-gate --format markdown
uv run --extra dev patchrail evidence application-dossier --format markdown

The gate exits non-zero until PyPI telemetry, permissioned external evidence, and visible review links are real rather than placeholder-derived. The dossier command compiles local evidence, upstream contribution links, blocked dependencies, reviewer_quick_checks, and the submission policy, but it does not submit the application and keeps maintainer tap required. The quick checks include the 10-second no-install demo, the pre-PyPI source install smoke, the fail-closed application gate, and the local application dossier; all but the optional GitHub source install run without network access or write actions.

License

Apache-2.0.