MergeLoop

MergeLoop is a merge queue for GitHub. Add a label to a pull request, and MergeLoop rebases it onto its base branch if it has to, waits for the required checks, and merges it.

Status: early. Expect rough edges, and tell us what breaks.

This README is also the website's docs, at mergeloop.ai/docs. DOCS in crates/web/src/docs.rs picks its ## sections by heading, and a test fails when one is renamed.

MergeLoop was previously called Mergepatrol. A repo set up before the rename keeps working as it is: MergeLoop still reads its config file at .mergepatrol/mergepatrol.yml, where the label the file leaves out stays mergepatrol, and updating the repo's skill moves it from skills/mergepatrol to skills/mergeloop. Self-hosting still reads the MERGEPATROL_* environment variables. The source repo is now agent-labs-dev/mergeloop; GitHub redirects the old name.

Try it

The hosted MergeLoop at https://mergeloop.ai runs the public GitHub App Merge Loop (merge-loop). You bring your own model API key.

1. Sign in with GitHub at https://mergeloop.ai.
2. Install the App on your organization or account, and choose its repos. GitHub sends you back to the dashboard.
3. In Settings, pick a repo and Set up. MergeLoop opens a PR that adds its config file, .mergeloop/mergeloop.yml. Merge it, and the repo queues.
4. In Settings, add an Anthropic or OpenAI API key. Create one for MergeLoop alone, with a spend limit.
5. Add the mergeloop label to a PR on GitHub. The dashboard's Queue page shows each queue in the order it merges, each PR's stage, and what holds it; a PR opens on GitHub.

Public repos are free. Private repos cost $15 a seat a month, after a free trial: see Pricing. To run your own, see Run it.

How it works

What a queued PR needs

A labeled PR gets ready on its own first, and no PR waits for another's: the agent resolves a conflict with its base, its checks run, and the agent fixes what fails. Then the agent reviews it. A PR that this cannot settle goes on to the queue as it is, which ejects it. A stack gets ready as one, and a PR from a fork skips this. To run all of it in the queue instead, one PR at a time, a self-hosted MergeLoop sets MERGEPATROL_PREP=false.

A labeled PR keeps its place in line, on hold, until GitHub would merge it and the queue can take it:

• It is not a draft.
• It has the reviews its branch protection or rulesets require, and no requested changes from a required reviewer. MergeLoop reads GitHub's review decision, so a repo that requires no review needs none.
• It targets the default branch, or a branch in branches of the config file.
• With Automatic review on, the agent's review holds nothing, and every review thread on the PR is resolved: its author fixed or answered each comment, and a human answered anything the review asked.
• On the hosted MergeLoop, a private repo has a subscription, and a public repo's workspace is under the fair-use limit.

Then it runs alone or tested in a batch, and merges once its checks pass. Alone, it is rebased unless GitHub can already merge it as it is: its checks passed on its head, it has no conflict, it is not a stack, and the branch is not strict about being up to date. That skips a run of CI, at the cost of merging a PR that was not tested with the branch's newest commits. Turn on "Require branches to be up to date" to always rebase. Only the base branch's required checks count. A branch with no required checks counts every check on the commit, so turn on required checks for CI that must pass. The merge uses the repo's default merge method on GitHub. The PR's comment and the dashboard say what holds a PR.

When a rebase has conflicts, an agent resolves them. Claude is the default. A plain git rebase runs first, so the agent runs only on real conflicts. A conflict found in the queue goes back to getting ready, keeping its place, so the agent holds up no other PR.

A PR that keeps up with its base branch by merging, as when its author never force-pushes, is brought up to date the same way: MergeLoop merges the base branch into it and pushes that merge commit without force. A rebase would replay each of its commits and conflict again in files its merges already resolve. A PR whose rebase conflicts while a merge of the base branch is clean is merged too. A conflict in the merge goes to the agent once, on the merge, and the same checks hold: no file outside the PR, no conflict markers left. A repo that merges PRs by rebasing them always gets a rebase, as GitHub would replay the merge's commits too. A rebase that runs out of time merges the base branch in instead; the time running out is never a reason to eject the PR.

This is the beginning of the README. Read the rest at the original. Read the full README ↗