Auto-merge bot PRs across a fleet of repositories — only when a computation, not a person, says the diff is safe.
Built for a fleet of ~80 repos where Dependabot and scheduled coding agents
open more pull requests than anyone can read. Review was the bottleneck, and
the first attempt to fix it — an agent that "enabled auto-merge on anything
green with an eligible shape" — judged shape by eye, armed a 197-file diff to
land unreviewed, and later let a major version merge 130 seconds after it was
force-pushed into a PR that had been judged as a minor. Every rule in this
repo is the fix for something like that. DECISIONS.md tells
each story.
Four conditions. All required. No overrides. (Then the circuit breakers below get a veto.)
- The diff's shape is on the allowlist — computed from the changed file paths, never from the title, the branch name, a label, or the loop that claims to have produced it.
- The repo has at least one required status check that actually runs on
pull requests, and at least one of them is a correctness gate — a
test/build/lint/typecheck job, judged by name or declared in
repos.ymlcorrectness_checks. A shape match on an ungated repo does not merge; a repo with auto-merge on and only a security scan required is DRIFT. - Every required check is green at the exact commit that was judged —
the newest run of each name, across every page of check runs;
skippedcounts only for names the repo lists inmay_skip; still-running is not green — and that commit is what gets merged (gh pr merge --match-head-commit). Nothing is ever armed: an arm is standing permission to merge future content on the strength of a judgement about past content. - Those checks ran against the base branch's current head. A PR's
base.shais the base its checks saw; if the branch has moved since — by anyone, or by this sweep's own previous merge — the green is stale and the PR waits. One merge per base branch per sweep; a stale Dependabot PR is asked to rebase, a stale loop PR routes to review.
| Shape | Merges when | Never merges |
|---|---|---|
lockfile-only |
only regenerated lockfiles changed and every version delta inside is patch/minor | a major hiding in uv.lock |
dependency-bump |
manifest + lockfile, every delta patch/minor (read from the PR body — the title of a group bump names no versions) | any group containing a major, a 0.x minor, or a SHA-only bump |
tests-only |
every file is a brand-new test file (status added in the compare of exactly the judged base...head), none is harness/config, none shares a name with an existing path, and none contains a skip/xfail/.only/pytestmark/SkipTest/__test__ marker or a duplicate test name — and the repo opted in (allow_tests_only) and CI's test counts show more tests ran at head than at base (Test-count evidence below) |
one source file alongside forty tests — there is no partial credit; any change to an existing test file (modified, removed, renamed, copied) routes to a human |
data-artifact-only |
every path is inside a directory the repo has explicitly opted in via data_dir |
anything, if the repo never opted in |
ci-fix |
every added line matches an explicitly reviewed whitelist of action bumps | a workflow edit that merely reads like a fix |
content / mixed / empty |
only on the reviewed path below | without the repo's opt-in, always routed to a human |
unreadable |
— | always routed to a human |
A content veto sits on top of all of it: if any changed path is editorial content, the PR does not auto-merge whatever its shape. And an unreadable diff vetoes — "I could not check" never resolves to "there is nothing there".
The allowlist answers "is this diff safe by its shape". A feature PR never
is, so it waits for a person. A repo may name a second answer:
allow_reviewed: true in repos.yml. Then a PR in the gate's queue whose
shape is not on the allowlist merges when all of these hold:
- everything a shaped PR needs: not a draft, auto-merge allowed, a required correctness check, every required check green, a fresh base that is not red, no breaker;
- the newest
merge-gate/reviewcommit status on the exact head the gate judged issuccess. A status belongs to a commit, so a push after the review leaves the new head unreviewed, and--match-head-commitmerges that head or nothing.
allow_reviewed_content: true extends it to PRs the content veto stops, and
is read only where allow_reviewed is also true. An unreadable diff is never
reviewable.
Two more kinds of PR take this path in an opted-in repo:
- a
tests-onlyPR the shape rules turned away (noallow_tests_only, or it edits an existing test file). It merges on the review, so it does not owe the shape's test-count evidence; - a PR an owner opened (author login in
GATE_OWNERS). Without the opt-in a person's PR is never in the queue. With it, a ready PR of theirs is judged like the fleet's output, except that no shape merges it: only a review does. A draft is still skipped, so a draft is how its author holds one back. A PR from anyone else is never in the queue.
gate_required_checks. A private repo on a free plan cannot have branch
protection, so GitHub reports no required checks for it and the gate filed
it as drift, permanently. Such a repo may list the check-run names in
repos.yml; the gate then requires those on that base (one must still be a
correctness check). Nothing but the gate enforces them, which holds where
the gate is the only thing that merges. GitHub's own list wins where one
exists. A PR that edits anything under .github/ never merges on declared
checks: it could redefine them. That is read from the compare of the exact
range merged, renames included. The ledger row carries review (the state read) and its reason
reads mixed (reviewed); green: ….
The gate does not review; it reads a verdict. Who posts the status, and how hard they looked, is the operator's to arrange. Anyone with push access can post one, the PR's own author included, so this is a separation of runs, not of credentials.
A green, allowlisted PR is still HELD — its own report section and ledger decision, never merged, applied in dry runs too — when:
- the repo is paused in
repos.yml(merge_gate_paused: true); - a revert of a gate merge was found on its base branch. Each sweep
starts by scanning every base branch the gate merged into in the last 14
days for
This reverts commit <sha>naming a gate merge, or GitHub'sReverts owner/repo#Nnaming a gate-merged PR, and records a pause in the ledger. The pause clears only when that revert's sha is listed in the repo'smerge_gate_ack_reverts; time passing does not clear it. A repo that could not be scanned this sweep is held for the sweep; - the repo already took
MERGE_GATE_MAX_PER_DAY(default 3; per repomerge_gate_max_per_day) real gate merges in the last 24 hours, counted from the ledger plus this sweep's own merges; - any correctness check on the base branch's head is red (newest run per
name;
cancelleddoes not count).
No scan of a new test file's text can prove it doesn't end the run early
(os._exit reached through __import__, importlib, setattr, ...). A
count of what ran can: if a new file stops the run, fewer tests pass. So a
repo's CI uploads an Actions artifact named verify-report holding one file,
verify-report.json:
{"schema": 1, "repo": "owner/name", "commit": "<tested sha>",
"stages": [{"stage": "unit", "tests": 120, "passed": 118, "failed": 0, "skipped": 2,
"passed_ids": ["tests/test_a.py::test_one", "..."]}]}from one workflow, declared per repo in repos.yml as
verify_workflow: .github/workflows/ci.yml, on every pull_request (commit
= the PR head sha, not the refs/pull/N/merge sha) and every push to the
default branch (commit = the pushed sha). Without verify_workflow there is
no evidence at all (VERIFY — no evidence: verify_workflow is not set ...).
Provenance. For a PR head the gate takes the newest completed run of
exactly that workflow path with event pull_request on that head_sha; for
the base, the newest completed push run of it on the base branch. Only that
one run counts: it must have concluded success and carry exactly one
verify-report artifact. If it failed, was cancelled, or has no (or an
invalid) report, that is no evidence — an older run is never used instead.
Other workflows' artifacts, workflow_dispatch runs and the like are ignored.
The run id, workflow path and event go into the ledger.
Validation is strict — schema 1, this repo, exactly this commit, stages
non-empty and uniquely named, counts non-negative integers with
passed + failed + skipped == tests. passed_ids is optional per stage; when
present it must be a list of non-empty strings, sorted (Python sorted(),
i.e. by code point) and unique, with exactly passed entries. More than
200,000 IDs in one report is no evidence. Anything else is no evidence, with
the reason. Reports are read once per commit per sweep, and only for a PR
whose required checks are already green.
A tests-only PR (in a repo with allow_tests_only: true) merges only
with evidence for both its head and the base its checks ran against, and
only when: no test failed at head; every stage the base ran is present at
head; per stage, tests and passed did not drop and skipped did not rise;
where both head and base list passed_ids for a stage, every ID that passed
at base passed at head; and the total grew by at least the test cases the diff
adds (def test… in Python, it(/test( in JS/TS) — or by at least one when
they cannot be counted. With IDs, that growth is new IDs: base IDs all pass at
head and there is one ID per pass. Otherwise it routes with the reason, e.g.
VERIFY — stage e2e: tests 70 -> 64 at head or
VERIFY — stage unit: tests/test_a.py::test_one passed at base but not at head.
Without IDs a swap (one old test stops running, one new one starts) leaves the
counts unchanged, so emit passed_ids when the runner can.
require_verify_evidence: true in repos.yml applies the first two
conditions (no failure at head, no vanished stage) to every shape the gate
merges in that repo. Either way the head and base run, workflow, event and
counts (never the IDs) go into the ledger row's artifacts.verify.
What this does not defend against. The report is produced by CI that
runs the PR's own code: a pull_request run executes whatever the PR adds,
and that code can write any report it likes, or rewrite the step that writes
it. The evidence defends against accidental weakening — an agent's new test
file that ends the run early, a test that quietly stopped running — not a
deliberately malicious PR. That is why tests-only auto-merge stays opt-in per
repo (allow_tests_only), and why the report should be computed from the
runner's own result files (JUnit XML, --json) in a step after the tests,
not from anything the tests themselves write.
Every verdict — merged, would-merge, stale, routed, skipped, drift, held,
no verdict — appends one JSON line to MERGE_GATE_LEDGER (default
~/.local/state/fleet/merge-gate-ledger.jsonl; off disables it, and a
real run then refuses to start with exit 4, because the breakers above
read this file). A detected revert appends a pause row. Rows carry the
repo, PR, judged head and base sha, shape, tier (the PR's bump severity,
when it declares one), each required check's name/conclusion/app,
green_by_skip, changed paths, source (dependabot / loop / other), the
decision and reason, dry_run, the merge commit sha and the sweep's run
id. A sample:
{"artifacts":{"count":1,"paths":["uv.lock"]},"base_ref":"main","base_sha":"base0","checks":[{"app":"github-actions","conclusion":"success","name":"ci"},{"app":"github-actions","conclusion":"skipped","name":"test"}],"decision":"MERGED","dry_run":false,"event":"verdict","green_by_skip":true,"head_sha":"h7","merge_commit_sha":"9f2c1e7d4b3a0000000000000000000000000000","pr":7,"reason":"lockfile-only; green: ci, test (green by skip: test)","repo":"o/r","run":"20261115T081452Z-5","shape":"lockfile-only","source":"dependabot","tier":"patch","title":"bump x from 1.0.0 to 1.0.1","ts":"2026-11-15T08:14:52Z","v":1}One writer (the sweep) appends under an exclusive lock, so a single file is
safe. It is not the control plane's per-run Ledger (one committed file per
loop run): that lives in another repository and a commit per sweep is the
wrong cost for a record read back every half hour. To ingest it there, read
the JSONL with gate_ledger.read() and record one summary per run id —
for example _ledger.record("merge-gate", "produced", "<n> merged", targets=[...repos merged...], counts={decision: n, ...}) — keyed on the
last run already ingested, so each sweep lands exactly once.
sweep(record=False) lets a read-only consumer ask the gate without
appending.
- Never runs
gh pr merge --auto. It disarms any arm it finds. - Never merges a PR a human opened, whatever the diff looks like.
- Never merges a draft.
- Never renders a failed API read as a verdict. A PR GitHub did not answer about is reported in its own section, not filed as decided.
- Never reports a drained queue it did not fully enumerate. Search endpoints cap silently; it lists per repo and cross-checks the total.
pip install "merge-gate @ git+https://github.com/gr8monk3ys/merge-gate@v0.10.0"That puts three console scripts on PATH — merge-gate, ci-watchdog,
classify-pr — so the gate runs from anywhere, not only from a checkout.
Running the files directly still works and is equivalent.
Needs Python ≥ 3.11. An authenticated gh is used
when it is present and working; when it is not, the same calls go over the
REST API instead (see Transport below), so no binary is strictly required.
export GATE_OWNERS="you,your-org" # every account the fleet lives under
merge-gate # report only — the default
DRY_RUN=0 merge-gate # merge judged heads, label the restThe report separates would merge / stale base / routed to review / skipped (ungated repo) / drift (auto-merge on, no correctness gate) / held by circuit breaker / no verdict (GitHub did not answer — retry, not a finding).
| Variable | Default | Meaning |
|---|---|---|
GATE_OWNERS |
(required) | Comma-separated users/orgs. An owner that yields zero repos aborts the sweep rather than silently shrinking the fleet. |
DRY_RUN |
1 |
0 to merge and label. |
INCLUDE_BOTS |
1 |
0 to ignore Dependabot. Bots are roughly four fifths of a real queue; leaving them out is how a full queue reports as empty. |
ONLY_PUBLIC |
unset | 1 to skip private repos — for GitHub's capped private-repo Actions minutes, not for safety. |
SWEEP_BUDGET_SECONDS |
unset | Stop the walk after this many seconds and report what was reached. Checked while listing repos and before each PR is decided, never inside one. |
GATE_WORKERS |
8 |
How many GitHub reads run at once: repo listings during enumeration, and per-PR reads during the sweep. Writes are always serial. |
GATE_REPOS_YML |
./repos.yml |
Path to the optional repos.yml. Absolute is safest — installed as a package there is no "next to the source file". |
MERGE_GATE_LEDGER |
~/.local/state/fleet/merge-gate-ledger.jsonl |
The merge ledger. off disables it (report-only runs only). |
MERGE_GATE_MAX_PER_DAY |
3 |
Real gate merges per repo per rolling 24h; repos.yml merge_gate_max_per_day overrides per repo. |
GH_TRANSPORT |
auto |
gh forces the binary, rest forces the REST API. auto uses the binary only when it can actually authenticate. |
| Code | merge-gate |
ci-watchdog |
|---|---|---|
0 |
The sweep ran and reached verdicts. It may still be incomplete — the report says so in its own section — but something was judged. | Nothing blocking was measured. |
1 |
— | A required check is red at an open PR's head: every merge in that repo is blocked. |
3 |
The budget ran out before a single PR was judged. The report prints STOPPED AT BUDGET, and the status is non-zero so a scheduler shows the run red instead of green over a sweep that did not happen. |
|
4 |
A real run (DRY_RUN=0) could not write the merge ledger, and refused to start. |
Reads run in parallel (GATE_WORKERS); verdicts and writes run serially,
in queue order, after each PR's reads are in. The order matters: a verdict
depends on which base branches this sweep has already merged into, and
that is only known once every earlier PR has been decided (rule 4 above).
Per-repo facts — allow_auto_merge, the required checks on a base branch,
that branch's head — are read once per repo per sweep, not once per PR.
Before a real merge the base head is re-read once more, uncached, so the
"checks ran against the current base" rule is enforced at the moment of the
write and not against a value cached minutes earlier.
| Script | Question it answers |
|---|---|
classify_pr.py |
What shape is each open PR, and would it merge? Pure classifier; --validate runs the self-tests plus any live fixtures you add. |
merge_gate.py |
Merge what earns it, at its judged head. Label the rest needs-review. |
ci_watchdog.py |
Is each repo's default branch still green — and since when? A red default branch blocks every merge in that repo and looks identical, from outside, to a repo with nothing to do. One repo sat that way for 37 days holding 15 mergeable PRs. |
verify-gates.py |
Does every required check actually fire on pull requests? A required check that only runs on push never goes green on a PR, so nothing can ever merge. (A script, not an importable module — it is not installed.) |
gh_transport.py |
Can this environment reach GitHub at all, and by which route? --whoami answers; --difftest proves the two routes agree. |
Optional: repos.yml (see repos.example.yml), looked for at
GATE_REPOS_YML, else repos.yml in the working directory. Per repo it
reads data_dir (opt-in data paths), may_skip (required checks that may
pass as skipped), correctness_checks (check names that are gates despite
their names), merge_gate_max_per_day, merge_gate_paused and
merge_gate_ack_reverts, allow_tests_only, require_verify_evidence,
verify_workflow, allow_reviewed, allow_reviewed_content and
gate_required_checks.
Every absent field is the strict value. The
merge policy itself is constants at the top of classify_pr.py, and
changing what merges is a one-line, deliberate edit.
A scheduled runner executed the gate 15+ times over three weeks, reported
"GitHub access is not enabled for this session" each time, and skipped.
Every script shells out to gh, so the gate had not declined to arm anything
— it had never run, and each "queue drained" was a report about a sweep that
did not happen.
gh_transport.run(argv) takes the same gh argv the scripts already build
and issues it against the REST API when the binary cannot authenticate. Call
sites are unchanged, deliberately: those argv strings encode detail that is
easy to lose by hand (--paginate with a line-per-record jq,
--match-head-commit, gh's uppercase visibility). Credentials come from
GH_TOKEN/GITHUB_TOKEN, then gh auth token, then git credential fill —
the last being the same question git asks before a push, so in a runner that
can push, this can read.
Only the argv forms this package issues are modelled. An unmodelled form exits nonzero rather than approximating — every caller already reads that as "GitHub did not answer" and fails safe, whereas a plausible wrong answer would be filed as a fact about a pull request.
python3 gh_transport.py # jq-subset selftest, no network
python3 gh_transport.py --whoami # which transport, is there a credential
DIFFTEST_REPO=you/repo python3 gh_transport.py --difftest # both routes, livepip install ".[dev]"
pytest # pure: no network, no gh
python3 classify_pr.py --validate--difftest is deliberately not in CI: it needs a credential and a real
fleet to compare against. It is the operator's check, run before trusting the
REST route.
On Windows, run pytest from Git Bash (or with Git's usr/bin on PATH):
the transport's timeout tests shell out to sleep, which PowerShell and
cmd.exe do not have.
The tests are the policy written as statements — a group is as risky as its
worst member, the sentence period is not part of the version, only
"dirty" is a conflict verdict. Read tests/test_policy.py as the spec.
Extracted on 2026-08-28 from the private control plane that runs it on a schedule. The numbers in the comments are real. The control plane vendored a copy for a month and the two drifted; as of 0.2.0 it installs this package as a dependency instead, which is why the entry points and the transport live here rather than there.
GPL-3.0-or-later.