mergeproof 1.0.0

Proof before merge. Pull requests earn their merge with evidence, not claims.

Documentation · Quickstart · Checks · Examples · Changelog

A pull request says "added tests, verified on staging". That costs nothing to type. mergeproof turns it into something CI can check: one YAML file in the repository says what a change must prove before it merges, the action checks the proof on every push, and the same file tells coding agents what to produce before they open the PR.

_{A real comment. One pill per rule, then only what blocks the merge and what to do about it; the rest is the receipt.}

How it works

• One policy file. A rule pairs a when (paths, labels, title, base branch) with what it requires: checks with parameters. Nothing to script.
• Evidence, not attestation. Tests must be in the diff. Jobs must be green on the head commit. Links must resolve at their source. Sign-off is a human approval bound to the commit; a new push invalidates it.
• One required status. Rulesets require mergeproof; the policy decides what stands behind it, CI jobs included. When no rule applies, nothing is posted and nothing blocks.
• Agents read the same file. They learn what to prove and check their own work before opening the PR. They cannot approve anything.

Quickstart

1. Write the policy. mergeproof init writes a starter; this is the shape:

# mergeproof.yaml
version: 1
rules:
  - id: source-needs-tests
    description: Source changes ship with tests for the touched module.
    when:
      paths: ["src/**/*.py"]
    require:
      - check: tests.changed
        with: { map: { "src/{pkg}/{name}.py": "tests/**/test_{name}*.py" } }
      - check: ci.job_passed
        with: { name: "^unit", regex: true }

  - id: fix-needs-live-evidence
    description: Bug fixes show the behaviour before and after on staging.
    when:
      title: "^fix"
    require:
      - check: evidence.links
        with: { key: traces, min_pairs: 1, verify: http }
      - check: review.human_verified
        with: { accept_approval: true }

2. Add the workflow. Full version with comments: examples/github-workflow.yml.

# .github/workflows/mergeproof.yml
on:
  pull_request:
    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
  issue_comment: { types: [created, edited] }
  check_suite:   { types: [completed] }
jobs:
  gate:
    if: github.event_name != 'issue_comment' || github.event.issue.pull_request
    runs-on: ubuntu-latest
    permissions: { contents: read, pull-requests: write, statuses: write, checks: read }
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.repository.default_branch }}   # policy from the base branch
      - uses: Aryamanz29/mergeproof@v1
        env:
          MERGEPROOF_PR_NUMBER: ${{ github.event.issue.number || github.event.pull_request.number }}

3. Require the mergeproof status on your default branch. Until you do, the gate only reports, which is the right way to roll it out.

Before you push

mergeproof explain runs the policy against the working tree and prints what is still missing, in the same words the PR comment will use. Agents run it in their loop; people run it before opening the PR.

pip install mergeproof            # or: uv tool install mergeproof, uvx mergeproof
mergeproof explain                # what this diff must prove
mergeproof template               # the evidence block still missing, ready to paste
mergeproof agent-prompt >> AGENTS.md

What it can check

Parameters for each: mergeproof checks, or the checks reference. Anything vendor-specific is a plugin: the Langfuse and Braintrust verifiers are a dozen lines each.

Evidence

What the contributor supplies goes in the PR description as a fenced block that agents can write and machines can read. mergeproof template prints the one a change still needs.

```evidence
environment: staging
traces:
  - what: search with an empty query
    before: https://www.braintrust.dev/app/acme/p/service/logs?r=b6f98332e178f658
    after:  https://www.braintrust.dev/app/acme/p/service/logs?r=db0100b2192984af
```

Everything else is found in the pull request itself: the diff, the check runs, the reviews.

Where it reports

Run without installing

uvx mergeproof explain
docker run --rm -v "$PWD":/repo ghcr.io/aryamanz29/mergeproof check --local

Images are tagged X.Y.Z, X.Y, X and latest per release, edge for main.

Documentation

aryamanz29.github.io/mergeproof

How it compares

Danger runs rules written in JavaScript and comments on the PR. policy-bot enforces approval policies from GitHub-native data. Checklist actions fail on unticked boxes. Hosted evidence gates evaluate your artifacts on their servers. mergeproof is declarative, has a notion of evidence that can be verified at its source, explains itself to agents, and runs entirely in your CI.

Contributing

make setup, then make lint typecheck test. Pull requests here are gated by this repository's own mergeproof.yaml. See CONTRIBUTING.md. MIT licensed.