Skip to main content

Misfire

Know why the build misfired.

CI PyPI Python License: MIT

An open-source GitHub Action that, when a build goes red, runs an agentic AI investigation of the failure and posts an advisory PR comment — explaining the root cause and classifying the failure as real vs. likely flaky. Advisory only: it never blocks, merges, or changes code.

Bring your own key. Misfire runs on Claude or OpenAI (pick with --provider; the OpenAI path also drives OpenAI-compatible endpoints like GitHub Models / Copilot). It never provides an API key — you set your own, and every analysis is billed to your account. The local --no-ai mode needs no key.

How it works

On a red build, Misfire runs a tool-using agent over four shared, mockable tools:

  • get_failing_logs — the failing CI job logs
  • get_pr_diff — the change under test
  • get_test_history — past pass/fail rate (powers the real-vs-flaky verdict)
  • post_pr_comment — the single write action

Each provider is an adapter behind one seam (misfire/agents/) — Claude and OpenAI today, more easily added — so the shared tools and prompt don't change when you switch provider with --provider.

Usage

Add a workflow that runs after your CI workflow and comments on red builds. Using the decoupled workflow_run trigger means Misfire gets a write-scoped token (so it works on fork PRs) and can never block or slow your CI job:

# .github/workflows/misfire.yml
name: Misfire
on:
  workflow_run:
    workflows: ["CI"]        # ← name of the workflow to watch
    types: [completed]
permissions:
  contents: read
  pull-requests: write
  actions: read
jobs:
  explain:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    steps:
      - uses: ericmhayes/misfire-ci@v0
        with:
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ github.event.workflow_run.id }}

pr-number is optional: when omitted Misfire resolves the PR from the failed run's head commit via the GitHub API. This works for PRs from forks too (where workflow_run.pull_requests is empty), and it simply no-ops when the run has no associated PR (e.g. a push straight to the default branch).

Add your ANTHROPIC_API_KEY as a repository secret (bring-your-own-key). The built-in GITHUB_TOKEN supplies the pull-request-write / actions-read scopes.

Local / offline use

Analyze logs straight from a file or stdin — no GitHub, nothing posted. The result is printed to stdout.

# Deterministic, no model call, no key (the offline fallback):
misfire analyze --logs ci.log --no-ai
cat ci.log | misfire analyze --logs - --no-ai

# Full agentic diagnosis (needs ANTHROPIC_API_KEY), optionally with the diff:
misfire analyze --logs ci.log --diff change.diff

--no-ai gives a deterministic rule-based summary (failure category + the key log excerpt); the AI path runs the same agent and prints the advisory instead of posting it. Secrets in the logs/diff are scrubbed before anything is sent to the model.

Install (development)

git clone https://github.com/ericmhayes/misfire-ci.git
cd misfire-ci
pip install -e ".[dev]"

License

MIT — bring-your-own-key (you supply your own Anthropic API key).

Metadata

Release files for misfire-ci 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for misfire-ci 0.1.0
File Size Uploaded Provenance Actions
misfire_ci-0.1.0.tar.gz 44.4 kB With provenance Details for misfire_ci-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for misfire-ci 0.1.0
File Interpreter ABI Platform Actions
misfire_ci-0.1.0-py3-none-any.whl Python 3 none any Details for misfire_ci-0.1.0-py3-none-any.whl

Total release size: 80.6 kB

Release files / misfire_ci-0.1.0.tar.gz

Download URL misfire_ci-0.1.0.tar.gz
Size 44.4 kB
Tags Source
SHA-256 checksum
How to use checksums
29cd7857a208eaa17b822f373c24df97d987cf810244979af73ef619fb926ba0
BLAKE2b-256 checksum
How to use checksums
c443d64c9ac6d03d3d3d122d010439817c706e137edd8a9177946a9bb891fd2c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / misfire_ci-0.1.0-py3-none-any.whl

Download URL misfire_ci-0.1.0-py3-none-any.whl
Size 36.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d7f0658ce744b8c77b8dab9f8e88ad651e899c1e35232cb8a2ccf8b379891da
BLAKE2b-256 checksum
How to use checksums
420f70ac53950b1a0b4f8786d3ffd195d1f0330a560cf22884b1e62e62f8a481
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for misfire-ci 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for misfire_ci-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page