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 — see LICENSE.

Metadata

Release files for misfire-ci 0.1.1

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.1
File Size Uploaded Provenance Actions
misfire_ci-0.1.1.tar.gz 44.4 kB With provenance Details for misfire_ci-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 80.6 kB

Release files / misfire_ci-0.1.1.tar.gz

Download URL misfire_ci-0.1.1.tar.gz
Size 44.4 kB
Tags Source
SHA-256 checksum
How to use checksums
cc3096362f664cf550ea86c8a537fcb6ade693ffc09da77a8ba0615395139b64
BLAKE2b-256 checksum
How to use checksums
f3420616afdc5ac305ffd736887e11e85f34e6f111b8e0c4ead0a602fe198188
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.1-py3-none-any.whl

Download URL misfire_ci-0.1.1-py3-none-any.whl
Size 36.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
844eff6686cb432da68615519381b488db4090f9a49bfae00bfa5f4a3cadbc6f
BLAKE2b-256 checksum
How to use checksums
fb8334228aff9e629db34979818f3b199b2cadaa53d08e7559f16907fa6e5b68
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.1

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.1.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.1 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