Skip to content
agent-labs-devPublic

About

Merge queue for GitHub that resolves rebase conflicts with an agent. Hosted at mergepatrol.ai, or self-host it.

Topics

Resources

Contributing

Security policy

Stars

9 stars

Watchers

0 watching

Forks

Latest commit

 

History

877 Commits

Folders and files

Repository files navigation

MergeLoop: a merge queue for GitHub, with an agent on conflicts

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.

When a PR's required checks fail, MergeLoop first runs their failed GitHub Actions jobs again, once for each head, since a failure such as a dropped network request may pass on the next run. That needs the App's actions: write permission: an App created before this permission existed must be given it on GitHub, and until then the checks go straight to the fix. A check that is not a GitHub Actions job is not run again. If the checks still fail, an agent fixes them. It reads what GitHub shows of the failure, commits a fix on top of the PR, and the checks run again. After three fixes that do not make the checks pass, the PR is ejected. A PR gets three fixes in all, and a push from its author earns new ones. When the agent gives up because the failure is not the PR's to fix, as with a flaky test, an outage or a title since changed, an empty commit runs the checks once more, and a failure then ejects the PR. When what fails is a check of the PR's title, the agent sets a title that meets it, and the checks run the same way. A failure found in the queue goes back to getting ready, keeping its place, so the agent holds up no other PR. Without a model API key in the workspace's settings, no agent can fix the checks: a PR whose checks still fail after they run again is ejected, and its comment says to add a key.

Automatic review

Automatic review is on for every workspace with a model key: an agent reviews every queued PR before it takes its place in line. It reads the change and the code around it, and reports each thing it looked at with how sure it is.

The reviewer holds a PR to your repo's own instructions. It reads AGENTS.md and CLAUDE.md, and the docs they point to, and reports code that breaks a convention they state, citing the line, and a change that leaves a line in them out of date. A REVIEW.md tells it what matters in a review of your repo: what failure looks like there, paths to skip, how many small findings are worth reporting. It reads each of these files at the repo's root and in every directory the PR changes, a deeper one adding to those above it, as they are on the PR's base: a PR that edits REVIEW.md is reviewed by the old one. MergeLoop's own agent loads no other copy. REVIEW.md steers what the reviewer reports; it cannot lift the evidence rule below.

The reviewer must show a check that actually fails before sending a non-security change back, unless the repo's Review depth is Deep. For every non-security finding marked change, the reviewer names a runnable evidence command and, when needed, writes a focused test. MergeLoop then runs that command itself on the PR's head, with only the files the finding names. Only a failure MergeLoop saw in its own run counts; the reviewer's claim that it ran something does not. A passing command, a timeout or a command that could not start does not qualify.

Without that failure, the finding is cleared as a note and holds nothing; at Deep, a panel votes on it instead, as below for a security change. Cleared findings remain visible in MergeLoop's review. When a review is posted on GitHub, they appear under What it cleared. A review that clears everything posts no summary on GitHub. Nothing is silently dropped.

A security change with no failing command goes back only if fresh agents agree it holds. A hole often shows in the code alone, with no test to fail, so MergeLoop has three fresh agents check each such finding, at once, each in a checkout of the PR's head of its own. Each sees only what the finding claims and the code, not how the reviewer got there, nor the others' answers, and votes on whether it holds. It goes back to the author only when two of the three say it holds. Otherwise it is cleared as a note that says how the vote went. The votes, and why each agent cast its own, show on the finding in MergeLoop's review and in its thread on GitHub.

A change marked needs_human still goes to a human, as do kinds configured to always ask, such as migrations. Those paths do not require a failing command or a vote.

A change that meets these rules and its confidence bar goes back to the PR's author, often the agent that built it, never to a fix of MergeLoop's own: the author decides what to make of each finding. It comes as a GitHub review that requests changes, with a thread on its line for each finding, saying what to change, so GitHub too holds the PR until the review clears. A review that only asks a human is a comment. Shows it gives the command MergeLoop ran, what it printed and any test patch; a test too large for the GitHub comment is available in full from MergeLoop's review. The author works each thread: fix it and push, or reply with why it doesn't apply, then resolve it. Once every thread is resolved, MergeLoop dismisses its request for changes, approves the PR on GitHub, and the PR goes on to the merge queue with no human approval.

A push gets a new review, which checks each finding sent back, with the author's replies in front of it. It reads only the commits pushed since the head it sent them back on, and reports nothing about the rest of the PR unless those commits break it; after a rebase, or a merge of the base branch into the PR, it reads the whole PR again. A finding still there gets a reply in its own thread, which opens again, never a new comment. A thread whose finding is fixed, or whose reply holds up in the code, is resolved, and a review that sends nothing back dismisses the request for changes of the last. After three rounds that still send findings back, the next review asks a human instead. An author can also reply to a finding in its thread, mentioning the App: the agent reads the code again, answers in the thread, and withdraws the finding, resolving its thread, if the reply holds up.

A human is asked only about what the author cannot settle from the PR: a call on scope, product or design, access it lacks, a change outside the repo, or a kind the workspace always asks about. The agent then requests a review from the code owners of the lines in question, and puts each such finding in a thread on its line, with why it needs a human and what the agent already checked. Someone who can push to the repo answers each in its thread, on GitHub: resolving it says it is fine as it is, and a reply asks for the change it says. The PR's author's own reply is not an answer, as the change is theirs to push. Approving the PR answers every ask as fine, and requesting changes sends them all to the author. A reply that mentions the App, @merge-loop on the hosted MergeLoop, asks the agent to dig further instead: it reads the code again and answers in the thread. Once every ask is answered, the PR goes on, or, with a change asked for, keeps its place while the author pushes it, and the agent reviews it again knowing what was answered. Once the review lets a PR on, MergeLoop approves the head it reviewed on GitHub. That approval counts toward the branch's required reviews unless its rules ask for a human's. If the rules dismiss stale approvals, MergeLoop approves again once it has reviewed the new head. It never approves a PR its App opened, which GitHub doesn't allow.

Each kind of change has a bar: how sure the agent must be to send a change back to the author. A lower bar sends back more. The defaults: 60% for security, 70% for dependencies and for public APIs, 80% for everything else, and migrations always go to a human. A change under the bar shows as a note and holds nothing. Confidence alone never replaces the evidence requirement, nor a panel's vote.

Review depth sets how hard the review looks, and so what it spends. Standard, the default, is one reviewer, as above. Quick is one reviewer that reports only what could be wrong, leaving out what it checked and found sound. Deep is for code where one missed bug costs more than the extra review: three reviewers look at once, each fresh, in a checkout of the head of its own, and their findings merge, one per issue: two of the same kind about the same place, a few lines apart, are one. Then a panel of three fresh agents votes on every change, of any kind, that no failing command shows, as it does on a security change at any depth: it goes back to the author when two agree it holds. A deep review spends several times what a standard one does, which shows in what the dashboard's History says the agents spent. A repo sets it in its config file as review.depth.

Require resolved comments, on by default, makes the gate wait for every review thread on the PR to be resolved, whoever started it: the agent's, a human's or a bot's. It is the same rule as GitHub's "Require conversation resolution before merging", so a repo can turn that on in its branch protection too, to hold merges made outside the queue. A repo sets it in its config file as review.require_resolved. The App hears of a resolved thread from the pull_request_review_thread event: an App created before the event was added must subscribe to it on GitHub, or the queue sees the thread resolved only on its next read of the PR. Settings shows how the agent's confidence has held up against the humans' answers, to set each bar by. A workspace can turn automatic review off. It does not review PRs from forks: a human reviews those. A clean rebase by the queue keeps the approval, and so does a push that changes the same lines the same way as the approved head did, as a rebase onto a newer base does. A fix by the queue's agent, or a conflict it resolved, does not: the PR merges once the agent has reviewed that change, on its own.

Required checks that have not finished 3 hours after a rebase or a fix also eject the PR, with no fix, so a check that never finishes does not hold the queue forever. A required check that never reports at all goes sooner: once every check that did report has finished, the PR waits 30 minutes for the rest, then is ejected with a comment naming them. That is a PR that renames a required check, or a workflow that no longer runs it. A head on which no check has reported at all, as when CI has not started, waits out the 3 hours instead. Before it counts a check as never reported, the queue reads the head's GitHub Actions workflow runs: the 30 minutes do not run while one is still queued, waiting for an approval, or running. In a batch, either counts as a failure.

While a PR waits for its checks, PRs labeled meanwhile take their places behind it within a minute, as waiting or held, in the dashboard and in a PR's state. During a rebase or an agent's fix, they join once it is done.

An error outside the PR's job does not eject it. That covers GitHub being down, or slow to answer, as well as a rate limit. The PR keeps its place at the head of the queue, and its job runs again. Only after 30 minutes of such errors is it ejected.

Branches

The default branch has a queue, and so does each branch that branches in .mergeloop/mergeloop.yml lists, release say. A labeled PR joins the queue of the branch it targets, and is rebased onto that branch. A PR into any other branch is held, as is a PR stacked by hand on another PR's branch: a stack made with gh stack joins the queue of the branch the whole stack merges into. The queues of a repo take turns, one job each, so a busy branch does not hold another up; they share the repo's git cache, so two never run a job at once. A batch holds PRs into one branch only.

A PR retargeted to another branch leaves its queue, and joins the other branch's at the back. Deleting a branch closes the PRs into it, which leave its queue. A branch taken off the list holds its PRs. The settings in the file, on the default branch, apply to every branch's queue.

Batches

A queue that runs CI once per PR merges a few PRs an hour. So when several queued PRs have passed their own checks, MergeLoop tests them together:

  1. It merges them, in queue order, onto a branch mergeloop/batch-<PRs> at the base branch, and opens a draft PR from it, so the repo's pull_request CI runs on the combination. The draft's title is the first PR's title, plus a note, so a PR title check passes.
  2. When the required checks pass, it merges the PRs one by one, as they are: no rebase, and no second CI run. Each merge must leave the base branch at the tree that the batch tested, else it stops.
  3. It deletes the branch, which closes the draft PR.

When a batch fails, MergeLoop tests half of it next, and so on down to one PR, which runs alone: rebased, with its own checks. That PR is ejected; the rest merge.

A PR runs alone when its own checks have not passed, when it conflicts with the PRs ahead of it, and on a base branch that requires PRs to be up to date before they merge. MergeLoop reads that setting from the rulesets, and from classic branch protection with the App's administration: read permission. Without the permission, every base branch counts as requiring it. An App created before this permission existed must be given it on GitHub.

Stacks

A stack of PRs, made with gh stack, is one item of the queue: the label on any of its PRs queues the whole stack, and MergeLoop merges it all at once, with GitHub's asynchronous merge. Either every PR of the stack merges, or none does. GitHub merges a stack only when the required checks of each of its PRs passed.

  • The stack gets ready as one item, off the queue, like a single PR: a conflict on any layer rebases the whole stack, and it waits for each layer's checks. A failed check is fixed on the lowest layer it failed on, and the layers above it are rebased onto the fix. The layers share one fix budget.
  • The stack waits while any of its PRs is a draft or waits for a review.
  • The queue page lists a stack's PRs, top first, each with its title, checks and diff, and marks the one that holds it.
  • The agent reviews each layer on its own: what it changes over the layer below. A layer that a rebase or a push below moves, with its own changes the same, keeps its approval and is not reviewed again.
  • In a batch, the stack is one step: its top PR holds every layer below it.
  • Alone, MergeLoop rebases each layer onto the one below it, the bottom onto the base branch, and waits for each layer's checks. A layer that keeps up by merging, over a layer below that did too, has the layer below merged into it instead. Over a rebased layer, a layer is rebased. A failed check is fixed on the layer it failed on, and the layers above it are rebased onto the fix.
  • A failed stack is ejected whole.

Every merge goes through the asynchronous merge API, stacked or not. A merge still pending when MergeLoop restarts is waited for, not requested again.

PRs from forks

A maintainer queues a PR from a fork with the label, as any other. Its author is not trusted as the repo's own are, so the queue treats it differently:

  • It merges the PR only as it was when the label went on. MergeLoop reads that head from the labeled webhook, or, without webhooks, from when it first sees the PR. If the author pushes after that, the PR leaves the queue, and a maintainer adds the label again to queue the new commits.
  • It never tests the PR in a batch, whose draft PR runs CI with the repo's secrets. The PR runs alone, with the fork's own CI.
  • It skips getting ready. No agent runs on it, and running alone, it is rebased and its checks run again in the queue anyway.
  • It runs no agent on the PR: a plain git rebase, or merge of the base branch, only. A conflict, or a failed required check, ejects the PR, for its author to fix.
  • It pushes the rebase to the fork, which GitHub allows while the author allows edits by maintainers. Without that, a PR that needs a rebase waits on hold until they allow it. GitHub does not let the App push to a fork that an organization owns, nor push changes to workflow files to a fork: such a PR that needs a rebase is ejected, for its author to rebase.
  • While GitHub waits for a maintainer to approve the fork's workflow runs, the PR waits on hold.

A stack with a PR from a fork is not supported yet.

The agent's review is answered in its threads on GitHub, which MergeLoop hears of from the pull_request_review_comment, pull_request_review_thread and issue_comment events. An App created before those events were added must subscribe to them on GitHub; until then, only an approval or a request for changes answers the review.

Pricing

The hosted MergeLoop is free on public repos. Private repos cost $15 a month per seat, after a free trial of 14 days that needs no card. Either way, the agent runs on your own model API key.

  • Public repos have a fair-use limit across a workspace: 100 PRs joining a queue, and 50 jobs (rebases and fixes), an hour. Over it, waiting PRs go on hold, keep their place, and go on once the last hour is under the limit. A PR already running finishes.
  • Private repos need a subscription, started from the dashboard's Settings. Without one, their waiting PRs go on hold, with a comment that links there.
  • A seat is a developer whose PR joined a private repo's queue. They take it with their first such PR, and keep it until removed in Settings. A seat added mid-month is charged for the rest of it; a removed one drops off the next bill. A PR authored by an App, such as Dependabot, takes no seat, except a PR the build lane opened: that one is the PR of the developer whose daemon holds its build, and takes their seat as a PR they opened would.

A self-hosted MergeLoop has no limits, and bills no one.

Run it

GitHub webhooks wake a queue as soon as something changes, but GitHub only delivers them to a public https URL. On localhost, MergeLoop polls.

  1. Generate the secret key. It encrypts the GitHub App and the model API keys in the database. Keep it: without it, you must set MergeLoop up again.

    export MERGEPATROL_SECRET_KEY=$(openssl rand -base64 32)
  2. Start MergeLoop:

    docker compose up --build -d
    docker compose logs mergeloop | grep setup_token

    Or without Docker for MergeLoop itself, with Rust (rust-toolchain.toml picks the version) and Node 24 with pnpm:

    docker compose -f compose.dev.yml up -d   # or any Postgres 17
    (cd ui && pnpm install && pnpm build)     # the dashboard, which the binary embeds
    export MERGEPATROL_DATABASE_URL=postgres://mergepatrol:mergepatrol@127.0.0.1:54329/mergepatrol
    cargo run -p mergepatrol                  # prints the setup token

    Jobs then run as local processes, without a sandbox. If port 8080 is taken, set MERGEPATROL_BIND=127.0.0.1:<port> and MERGEPATROL_PUBLIC_URL=http://localhost:<port>.

  3. Open http://localhost:8080 and do the setup in the dashboard:

    1. Enter the setup token from the logs.
    2. Create the GitHub App. GitHub creates it with the permissions MergeLoop needs. If the button does nothing, the name is taken, even by an App you deleted: change it.
    3. Install the App on your organization or account, and choose its repos. GitHub sends you back to sign in.
    4. In Repos, set up the repos to queue. Each gets a PR that adds its config file: see Repo settings. Merge it, and the repo queues.
    5. In Settings, add your Anthropic or OpenAI API key. MergeLoop checks it with the provider, then stores it encrypted. Create a key for MergeLoop alone, with a spend limit (for Anthropic, in a workspace with one), so a leaked key costs at most the limit. For OpenAI, you can Sign in with ChatGPT instead, and Codex runs on your ChatGPT plan. MergeLoop signs in the way the Codex CLI does, which OpenAI does not support for other apps and could stop at any time: keep an API key to switch back to.
  4. Add the mergeloop label to a PR to queue it. MergeLoop creates the queue labels on each repo it queues.

Anyone with a GitHub account can sign in. Each installation of the App is a workspace, with its own repos and its own model API keys. A user sees the workspaces that GitHub lets them access. A session reads them from GitHub again every hour, so a new installation shows up, and a lost one goes, within the hour. A session lasts 30 days from its last use, and ends when GitHub stops taking the user's token: when they revoke it, or after 6 months, when GitHub's refresh token expires.

Environment variables

If you reach MergeLoop at another address than http://localhost:8080, set MERGEPATROL_PUBLIC_URL before you create the App: GitHub sends users back to it, and delivers webhooks there when it is https. To get webhooks on your machine, run a tunnel such as cloudflared tunnel --url http://localhost:8080 and use its URL.

Variable Default What it does
MERGEPATROL_DATABASE_URL (required) Postgres. Compose runs one
MERGEPATROL_SECRET_KEY (required) Encrypts the stored secrets. 32 bytes, base64. To rotate it, see Rotate the secret key
MERGEPATROL_SECRET_KEY_FILE A file that holds the secret key, instead of MERGEPATROL_SECRET_KEY. Compose uses one
MERGEPATROL_PUBLIC_URL http://localhost:8080 Where users reach the dashboard
MERGEPATROL_LABEL mergeloop The default trigger label. <label>:priority jumps the queue, and ejected PRs get <label>:failed
MERGEPATROL_POLL_SECS 60 How often to poll GitHub, in case a webhook is lost
MERGEPATROL_BATCH_SIZE 8 The default batch size: the most PRs tested together. 1 merges one PR at a time
MERGEPATROL_MAX_JOBS 4 The most rebase and fix jobs that run at once, across every queue
MERGEPATROL_DATA_DIR ./data The repo caches and the job outputs, with their transcripts. A job's output is kept 7 days
MERGEPATROL_BIND 127.0.0.1:8080 The dashboard address
MERGEPATROL_PROVIDER anthropic The agent's default provider: anthropic or openai
MERGEPATROL_MODEL claude-opus-5-5 The agent's default model. Required when the default provider is not anthropic
MERGEPATROL_EFFORT medium The agent's default effort

Run it with an App you made yourself

The hosted MergeLoop uses one public GitHub App, which we create by hand on GitHub, rather than with the setup in the dashboard. A self-hosted MergeLoop can do the same. Set the App's credentials, and the setup token and the App creation are skipped:

Variable What it is
MERGEPATROL_GITHUB_APP_ID The App ID
MERGEPATROL_GITHUB_APP_PRIVATE_KEY The private key, PEM
MERGEPATROL_GITHUB_CLIENT_ID The OAuth client ID
MERGEPATROL_GITHUB_CLIENT_SECRET The OAuth client secret
MERGEPATROL_GITHUB_WEBHOOK_SECRET The webhook secret. Optional: without it, MergeLoop only polls

The App needs the permissions in crates/github/src/setup.rs (manifest), each with the reason it is there, the callback URL <public URL>/auth/callback, the setup URL <public URL>/setup/installed, and the webhook URL <public URL>/webhooks/github, subscribed to the events in WEBHOOK_EVENTS in the same file. An App created before workflows: write joined the manifest must be given it on GitHub, or the push of a rebase or fix of a PR that changes .github/workflows is refused. An App created before the repository event joined WEBHOOK_EVENTS must be subscribed to it on GitHub (the App's settings, Permissions & events, Repository). Until then, a change to a repo's merge settings reaches MergeLoop at its next merge or within 15 minutes. An App created before the issues event joined WEBHOOK_EVENTS must be subscribed to it the same way, for the build lane: until then, a labeled issue becomes a task only when a daemon's claim reads the repo's labeled issues again, at most every 5 minutes, and a stuck one may become a task again when that read looks at the issue's newest label events (a few stuck builds per read, up to 1,000 events each) and finds the label, by its name, added again in or after the second the build got stuck. A label renamed meanwhile is not followed. With the webhook, putting the label on again makes it a task at once.

Rotate the secret key

Generate a new key, and set it in front of the old one, separated by a comma: MERGEPATROL_SECRET_KEY=<new>,<old>. Restart MergeLoop. At startup, it re-encrypts every stored secret with the new key, and logs how many. Then set only the new key, and restart again. Each session's GitHub token is re-encrypted at its next hourly check; a session idle through the whole rotation signs out.

On GCP, a deploy runs the old revision beside the new one for a while, and each must read what the other writes. Add each step as a version of the mergepatrol-secret-key secret, and deploy it:

  1. <old>,<new>: every revision can read both keys, and still encrypts with the old one.
  2. <new>,<old>: the new revision re-encrypts with the new key.
  3. <new>,<old> again, once the revision from step 1 has stopped: it re-encrypts what that one wrote with the old key meanwhile.
  4. <new>.

With Docker Compose, a plain restart does not recreate the container, so it keeps the old environment-backed key. After changing MERGEPATROL_SECRET_KEY or its secret file, run docker compose up -d --force-recreate and check the container logs for the startup re-encryption count before removing the old key. A restart alone is not a rotation.

Repo settings

Each repo sets its queue in .mergeloop/mergeloop.yml on its default branch. MergeLoop reads the file from there, so a PR cannot change its own settings. A setting the file leaves out follows the workspace, so an empty file is valid, and inherits everything. Settings sets the workspace's defaults for the label, batch size, model, effort, task models and CI fixes. They apply at once, with no PR, to every repo that follows them. A workspace that has set none follows the instance: on a self-hosted MergeLoop, the MERGEPATROL_* variables in Environment variables.

version: 1
label: mergeloop
batch_size: 8
agent:                  # the default model, which every task runs unless it overrides it
  provider: anthropic   # or openai
  model: claude-opus-5-5
  effort: medium        # low, medium, high, xhigh or max
  overrides:            # optional: a task's own model, over the default
    rebase:             # resolving a rebase's conflicts
      provider: openai
      model: gpt-6.1-sol
    fix:                # fixing failed checks
      model: claude-sonnet-5-5
    review:             # reviewing a PR, and answering questions about the review
      model: claude-fable-5-1
verify:
  - cargo check
fix_ci:
  enabled: true    # an agent fixes failed required checks
  attempts: 3      # 1 to 5 fixes of its checks before the PR is ejected
branches:          # queues besides the default branch's: exact names
  - release
review:            # over the workspace's automatic review settings
  enabled: true
  bars:            # how sure the agent must be to send a change back to the author: 50 to 100, or always_ask
    security: always_ask
    dependencies: 95
  require_resolved: true   # wait for every review thread to be resolved
  depth: deep              # quick, standard or deep: how hard the review looks

The agent runs Claude Code for Anthropic's models, and Codex for OpenAI's, with the workspace's key for the provider from Settings. A workspace signed in to ChatGPT runs Codex on its plan instead of the OpenAI key. A file that sets another provider than the instance's default must set its model too.

The agent has three tasks: resolving a rebase's conflicts, fixing failed checks, and reviewing. Each runs the default model unless agent.overrides gives it its own. A task that sets another provider than the default's must set its model too. The dashboard offers each provider's current models by name; the file takes the model's API id, and may name any model the provider serves. A file that still says resolver:, the section's old name, reads as agent:.

The verify commands declared in .mergeloop/mergeloop.yml run after an agent resolution or fix, before the publish. They must pass for that resolution or fix to land.

A repo with no verify commands, whether the setting is omitted or verify: [], gets commands derived from the run steps of its .github/workflows/*.yml and *.yaml workflows that run on pull_request. MergeLoop reads those files from its own checkout, and gives the commands to the reviewer and fixer. The reviewer uses them to build a failing check, and the fixer runs them after its change. The review evidence requirement still applies: MergeLoop must see the evidence command fail itself before sending a non-security change back.

Derived commands guide the agents; they never eject a PR. Only commands declared in verify gate a resolution or fix, so set that list to pin what must pass. GitHub's required checks still gate merging as usual. A workflow step that needs the workflow's context, a secret or another host is left out: the job has the toolchains, not your CI's services. If no usable commands remain, the reviewer follows the repo's docs to build a check; it still needs a failure MergeLoop can reproduce.

A fix runs in the sandbox, like a rebase, while the PR keeps its place at the head of the queue. It may change any file except those under .github/ and .mergeloop/. The agent gets each failed check's output and annotations, and for a GitHub Actions job, the end of its log. The log needs the App's actions: read permission: an App created before this permission existed must be given it on GitHub, or the agent works from the output alone.

A repo queues once its default branch has the file. MergeLoop looks for it in every repo every 5 minutes, and at once when a push webhook adds or removes it. Turn on and Turn off in Settings override the file, until you choose Follow the config file.

The dashboard edits the file through PRs. Set up opens a PR that adds a file with nothing but its version, and the mergeloop agent skill at .agents/skills/mergeloop/SKILL.md and .claude/skills/mergeloop/SKILL.md, so coding agents in the repo queue their PRs rather than merge them. A change to a repo's settings opens one that writes only what differs from the workspace. Both come from the branch mergeloop/config: a second change updates the open PR. A repo that queues gets the PR queued too, as does the PR that updates its skill, so it goes through review and checks like any other PR. The queue uses the new settings once the PR merges.

Update all in Settings brings every queuing repo up to date at once, and says what it did to each. For a repo behind, it opens a PR that rewrites the config file the way MergeLoop writes it now, keeping only what differs from the workspace, and a PR that writes the current skill, then queues them, so they go through the repo's review and checks like any other PR. It skips a repo with no config file, or one that does not parse. It leaves alone an open settings PR that changes the settings or would lose comments, and opens but does not queue a new PR that would drop comments from the file. Run it again as often as you like: a repo up to date gets no PR.

When the file does not parse, the queue pauses, and Settings shows why, until the file is fixed.

From an agent, or the API

MergeLoop serves an MCP server at /mcp, so a coding agent can do anything the dashboard does: queue a PR, take it out, read where it is and what it needs next, read the agent's review and the queue's history, change a repo's settings. Reviews, approvals and comments happen on GitHub, with gh. Every call acts as a GitHub user or bot: MergeLoop puts the labels on, comments, and reviews with their token, so GitHub checks they may.

A tool that refuses answers isError: true with the reason as text, and _meta.status, the HTTP status its route answered. A refusal a client must act on also names its kind in _meta.refusal: lane_off (the build lane is off), lost (you no longer hold the build), cancelled (its issue stopped being a task: give it back), unheard (heartbeat it, then ask again), may_not_push (give it back), merged (its PR merged: report it merged), closed (a person closed its PR without merging it: release it as stuck). When GitHub's rate limit is used up, your token's or MergeLoop's, the tool says when it resets, with _meta.status 503 and _meta.retry_after, the seconds until then: ask again after that.

The hosted endpoint is https://mergeloop.ai/mcp. It uses sessionless streamable HTTP: each POST carries one JSON-RPC message, with JSON responses to requests. GET returns 405 Method Not Allowed. Use the endpoint directly: following a redirect from the old host can break POST requests.

An MCP client that supports OAuth signs in with GitHub in the browser, as the dashboard does:

claude mcp add --transport http mergeloop https://mergeloop.ai/mcp

The client gets a MergeLoop session, and the GitHub token stays on the server. MergeLoop sends the sign-in back only to a loopback address, where native clients such as Claude Code, Codex and Cursor listen.

Before the client gets anything, MergeLoop asks you on a page of its own: which program asks (the name it registered with, which any program can choose), what allowing it gives it (it acts as you in MergeLoop, until it goes 30 days unused), and the code the sign-in carries, if any. Allow sends the client its sign-in; Deny sends it an error. Only that page, in the browser that signed in with GitHub, can answer, once, within 5 minutes. MergeLoop never remembers a yes: any program on your machine could register under the same name.

An agent without a browser, such as one in CI, passes a GitHub token instead: one from gh auth token, a personal access token, or a workflow's GITHUB_TOKEN. A fine-grained token also needs write access to issues or pull requests. MergeLoop never stores the token. It remembers its hash, in memory for 5 minutes, so calls in a row do not each ask GitHub again.

Send the header Authorization: Bearer <token>; no OAuth flow or MergeLoop sign-in is needed. Accepted token prefixes are ghp_, gho_, ghu_, ghs_ and github_pat_.

claude mcp add --transport http mergeloop https://mergeloop.ai/mcp \
  --header "Authorization: Bearer $(gh auth token)"

The mergeloop command

An agent with a shell lands a PR with the mergeloop command, which calls the MCP server:

mkdir -p ~/.local/bin && gh release download cli-latest -R agent-labs-dev/mergeloop \
  -p "mergeloop-$(uname -s)-$(uname -m).tar.gz" -O - | tar -xz -C ~/.local/bin
mergeloop            # the current branch's PR; or 123, owner/name#123, or its URL

~/.local/bin must be on your PATH for the last line to find it. If it is not, add export PATH="$HOME/.local/bin:$PATH" to your shell's profile and open a new shell.

Each push to main that changes it rebuilds it, for macOS and Linux on Apple silicon, Intel and Arm, into the cli-latest prerelease. Or build it: cargo install --locked --git https://github.com/agent-labs-dev/mergeloop mergeloop-cli.

mergeloop queues the PR, waits until it needs something of the agent, prints that need as JSON, and exits. brief says what to do, such as working the review's threads or fixing what got the PR ejected, and then is the command to run once done, which waits for the next need. The exit code says what kind it is: 0 work for the agent, 10 merged, 11 ejected, 12 waiting on a human, 2 an error. An agent runs it in the background, so it hears of the next need as soon as there is one, and nothing runs between needs. mergeloop call <tool> '<json>' runs any other tool, as a brief names it.

It talks to https://mergeloop.ai, or MERGELOOP_URL, and acts as the first of: MERGELOOP_TOKEN, a GitHub token; the session from mergeloop login; the GitHub token from gh auth token. The next_need tool is the same loop, for an agent over MCP alone.

mergeloop login signs you in to MergeLoop in the browser, through the same OAuth an MCP client uses. It prints a short code, such as WXYZ-2345; allow the sign-in only when the page shows the same code. It keeps the session in ~/.mergeloop/session/session.json, which only you can read. With it, mergeloop call reaches the tools marked Sign-in below, and acts as you rather than as a GitHub token. A session belongs to the server it was made on: sign in again for another MERGELOOP_URL. A session the server no longer takes, after 30 days unused or once GitHub stops taking your token, is an error that says to run mergeloop login again. mergeloop logout ends the session on the server and forgets it.

mergeloop daemon builds and lands the build lane's tasks on your machine: see The build lane.

A GitHub token reaches only the repos GitHub lets it read: MergeLoop cannot tell which of its workspaces such a token belongs to. The tools marked Sign-in work across a workspace, so they need the sign-in, and show only the workspace's repos you can read. Each tool takes the repo as repo, owner/name, or the workspace as workspace, its installation ID. get_session lists those IDs for a sign-in; with a GitHub token it answers status: "signed_out", with no workspaces, so a token's calls name a repo.

Tool Does Sign-in
get_changelog MergeLoop's newest changelog entries
get_session Who a sign-in is for, and its workspaces: signed_out for a GitHub token
list_queue The queues, in the order they take PRs: a repo's, or the workspace's Without repo
list_events A repo's queue events, newest first
list_history The PRs that left the queue: merged, ejected, or removed Yes
get_history_stats The queue's numbers over a window Yes
get_review_stats How the agent's review did over a window: what became of each change it asked for, reviews to pass, time asked of people Yes
list_repos The workspace's repos, and whether each queues Yes
set_repo Turns a repo's queue on or off, or back to following its config file Or a token with admin on the repo
pull_status Where a PR is, as /api/v1 below says, and its latest events
next_need What a PR needs next from the agent that queued it, with what to do: waits for a newer one with after and wait
queue_pull Queues a PR, or its stack. priority puts it at the front. Says when it goes on hold whatever the PR, or the agent has no model key
dequeue_pull Takes a PR, and its stack, out of the queue
get_agent_review The agent's review of the exact GitHub head currently published for a queued PR: what it found, what it sent back to the author, and what it asks a human
retry_agent_review Retry a failed automatic review of the exact current head, as its author, within the retry limit Yes
get_repo_config A repo's queue settings
propose_repo_config Opens a PR that changes a repo's queue settings Yes
get_repo_skill Whether a repo has the current mergeloop agent skill
update_repo_skill Opens a PR that updates a repo's mergeloop agent skill Yes
update_repo Opens and queues the PRs that bring a queuing repo up to the latest settings and agent skill Yes
get_repo_defaults What the workspace's repos follow where their config files say nothing Yes
set_repo_defaults Sets what the workspace's repos follow, at once and with no PR Yes
get_settings Which model API keys and ChatGPT login the workspace has Yes
set_api_key Sets a model provider's API key Yes
delete_api_key Removes a model provider's API key Yes
start_chatgpt_login Starts a ChatGPT sign-in: a code for the user to enter Yes
delete_chatgpt_login Removes the ChatGPT login Yes
poll_chatgpt_login Finishes the ChatGPT sign-in once the user entered the code Yes
get_review_settings The agent's review settings, and its track record Yes
set_review_settings Turns the agent's review on or off, and sets how hard it looks and how sure it must be Yes
get_build_settings Whether the workspace's build lane is on Yes
set_build_settings Turns the build lane on or off Yes
list_builds The build lane's builds: each issue, its status, who holds it and how lately they were heard from Yes
claim_build Claims one task for you to build, in a repo you may push to Yes
heartbeat_build Says you still work on a build you claimed Yes
get_build_task The task of a build you hold, as its claim gave it, for a daemon that restarted Yes
release_build Gives a build back, or marks it stuck with a reason Yes
mint_build_token A token for the repo of a build you hold, and nothing else: push pushes its branch and acts on its PR, read only reads Yes
open_build_pr Has the App open the PR of a build you hold, once its branch is pushed Yes
report_build Says whether the PR of a build you hold is landing, waiting on a human, or merged Yes
get_billing The workspace's plan and seats Yes
start_checkout A Stripe page to subscribe Yes
open_billing_portal A Stripe page to manage the subscription Yes
free_seat Frees a seat Yes

Each tool calls a route of the JSON API under /api, which the dashboard uses. A script can call the API itself with the same Authorization: Bearer header:

curl -H "Authorization: Bearer $(gh auth token)" \
  https://mergeloop.ai/api/w/<installation ID>/repos/<owner>/<name>/pulls/<number>/status

Read a PR's state from another app

An app that shows PRs, such as a PR list in an editor, reads what MergeLoop knows of them from /api/v1, instead of working it out from labels and the config file. It authenticates as the API above does: Authorization: Bearer with the viewer's GitHub token (OAuth, personal access token, or an App installation token) or a MergeLoop session. GitHub decides what the token can read. A repo it cannot read is a 404, the same as a repo that does not exist. A repo it can read is a 200, also when MergeLoop does not run there.

curl -H "Authorization: Bearer $(gh auth token)" \
  https://mergeloop.ai/api/v1/repos/acme/widgets/pulls/42
curl -H "Authorization: Bearer $(gh auth token)" \
  "https://mergeloop.ai/api/v1/repos/acme/widgets/pulls?numbers=42,43,44"

The second form reads up to 100 PRs of one repo, as { "pulls": [...] } in the order asked. Each PR reads:

{
  "repo": "acme/widgets",
  "number": 42,
  "url": "https://mergeloop.ai/acme/widgets/pull/42",
  "mergeloop": {
    "state": "on",
    "installed": true,
    "has_config": true,
    "override": null,
    "config_error": null,
    "hold": null,
    "missing_key": null
  },
  "queue": {
    "trunk": "main",
    "state": "held",
    "hold": {
      "reason": "review_required",
      "layer": null,
      "message": "waiting for a required review"
    },
    "priority": false,
    "position": 3,
    "stack": null,
    "batch_pr": null
  },
  "merged": null,
  "ejected": null
}
Field Says
url Where to open the PR: its lane in the dashboard while queued, the repo's settings while MergeLoop is off there, and the PR on GitHub otherwise
mergeloop.state on, off (no App on the repo, no config file, or turned off), or paused (the config file does not parse: config_error says why)
mergeloop.override on or off when turned so in the dashboard, whatever the config file says. null follows the file
mergeloop.hold Why any PR queued now goes on hold, before it is queued: { reason, layer, message } as in queue.hold, with reason no_subscription (a private repo on the hosted MergeLoop, without a subscription) or fair_use_limit. null when nothing about the repo holds it
mergeloop.missing_key The agent's tasks on this repo that the workspace has no model key for: { tasks, message, settings_url }, each task { task, provider } with task rebase (resolving a rebase's conflicts), fix (fixing failed checks) or review. Without the key, a conflict or a failed check ejects the PR. settings_url is where to add the key. null when the workspace has a key for each task
queue null unless queued. state is waiting, running or held. position counts from 1 in the order the queue takes PRs. stack is { number, layers } for a stack. batch_pr is the draft PR testing it, while it runs in a batch
queue.hold.reason draft, review_required, changes_requested, workflow_approval (a fork PR's runs wait for approval), fork_edits_off (a fork PR behind its trunk that does not allow edits by maintainers), no_queue (it targets a branch without a queue), no_subscription, fair_use_limit, reviewing (the agent's automatic review runs), review_asks (that review waits for a human's answers) review_changes (it sent findings back to the author, or a human answering it asked for changes, and it waits for the author) or unresolved_threads (review threads on it are unresolved, and the gate waits for them all). layer is the stack's PR that holds it
merged, ejected How it last left the queue: { at, sha } or { at, reason }. Both null while it is queued, and when it left otherwise

Every response has an ETag: send it back as If-None-Match for a 304 when nothing changed. Each caller, by its token, has 5,000 calls an hour, a 304 included, which x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-used and x-ratelimit-reset (Unix seconds) report. Past the limit, a 429 has a retry-after, in seconds. So does a 503 when GitHub's own rate limit is used up.

The build lane

The build lane turns labeled issues into merged PRs on your developers' own machines. Someone puts the repo's label on an issue written as a brief an agent can act on. A developer's daemon, mergeloop daemon, claims it, has an agent CLI on their machine (Claude Code or Codex, signed in with their own login) build it in a fresh worktree, runs the repo's verify commands, has a second agent review the change, and pushes it. MergeLoop's App opens the PR, labeled, so it is queued, and the daemon lands it like any PR: it works the review's threads and what the PR needs until it merges. The Builds page shows each build, who holds it and how far it is.

The lane is off until a workspace turns it on. It changes nothing for PRs people open. MergeLoop never approves a PR it built, since its App is the PR's author: what may merge with no human is up to the repo's rules (see Dark merges).

What an agent may do on your machine

Read this before you run the daemon. The daemon runs agents, and the commands they write, on your machine, from the text of an issue that anyone who can open issues in the repo may have written. Label only issues you would hand to an agent on your own machine.

access in the config file picks how far a build is confined. A build is everything that runs for it: the agent, the commands the agent runs, and the repo's verify commands, which the agent may have changed.

access = "workspace" (default) access = "full"
Writes Only the build's own folder, builds/<build>/ in the daemon's folder: its worktree and its temp folder. Not your checkouts, other builds, the clones' git metadata, the transcripts or the daemon's own files. Anything you can write
Reads Anything you can read, except the deny_read paths: by default your MergeLoop session and the places credentials live in a home folder Anything you can read
Prompts None: the agent works without asking None
macOS The agent CLI's own sandbox (Claude Code's, Codex's permission profile), and sandbox-exec for the verify commands. Checked on this platform.
Linux The agent CLI's own sandbox (Claude Code's needs bubblewrap and socat), and bwrap for the verify commands. The CLIs' read denials there are their documented behaviour, not checked by MergeLoop.
Elsewhere Refused when the daemon starts

What nothing stops, in either mode:

  • Reads outside deny_read. Your source, your dotfiles and anything else you can read, the agent can read.
  • The network. It is open, so what the agent reads it can send.
  • The macOS keychain. An agent can ask it, through security, for what it holds, as your own programs can; a git -c credential.helper=osxkeychain push of a ref that exists is a network call no sandbox sees.
  • Claude Code's temp folder. Its shell may always write /tmp/claude-<uid>, which every build shares: it does not run without it.
  • full access. It lifts the confinement and the read denials alike (--permission-mode bypassPermissions, --dangerously-bypass-approvals-and-sandbox). Tools that write outside the build's folder, such as a package manager's cache in your home folder, fail under workspace and need it.

An agent can also open your browser at a MergeLoop sign-in, as any program on your machine can. MergeLoop gives it nothing until you allow that sign-in on its page, and the page shows the code that mergeloop login prints, so you can tell your own sign-in from one you did not start. Allow only a sign-in you started: a yes to one you did not start gives that program a session that acts as you.

The daemon prints what does not hold on your platform when it starts. The details below say how each part is confined.

Turn it on

  1. In Settings, turn on Build lane, or call set_build_settings. While it is off, no daemon gets a new task, every lane tool but its settings refuses, and the Builds page says how to start. Turning it off is no stop button. It forgets the issues waiting and the builds merged. A daemon stops a build it holds when it next talks to MergeLoop, which can take as long as its heartbeat interval (5 minutes), and throws away that build's work it has not pushed. The build's record is kept: once the lane is on again, the build is a task again (when its daemon restarts, or once it goes 30 minutes unheard) and is built anew, or, when it has a PR, landed again. A PR that is already open stays in the queue and can still merge.
  2. Put the repo's label (its label setting, mergeloop by default) on an issue. An issue is a task while it is open and labeled, in a repo whose queue runs. A self-hosted App created before the issues event joined its events must be subscribed to it, as Run it with an App you made yourself says; until then a labeled issue becomes a task within 5 minutes of a daemon asking for work, rather than at once.
  3. On each machine that builds, install the mergeloop command and run mergeloop login once. Install the builder's agent CLI (Claude Code by default) and sign in to it, as mergeloop login does not. Do the same for the reviewer's: unless the config file names one, the reviewer is the other vendor's CLI when it is on your PATH (Codex for a Claude builder), else the builder's own. A CLI that is on your PATH but not signed in must be signed in, or the reviewer set in [reviewer] (agent, command), or turned off (enabled = false). Then run mergeloop daemon. It prints the builder's and the reviewer's commands when it starts: check them before its first build.

Only a developer whom GitHub lets push to a repo is given its tasks, and a token for it: an issue assigned to them goes to their daemon first, then unassigned ones; an issue assigned to someone else is never given to them. When a daemon claims an unassigned issue, MergeLoop assigns the developer on GitHub, for people to see who has it.

Run the daemon

mergeloop daemon signs in with the session from mergeloop login (never MERGELOOP_TOKEN or gh's token) and serves every workspace you belong to that has the lane on, until Ctrl-C. While it has a free slot, it claims a task and builds it:

  1. In its own clone of the repo and a fresh worktree, on the branch mergeloop/build-<issue>, the builder agent builds the issue.
  2. The repo's verify commands, as its config file declares them, must pass; when they fail, the agent gets one more run to fix them. A repo that declares none runs none here.
  3. The reviewer reads the change (see The local reviewer).
  4. The daemon commits the change as the App's bot, with you as Co-authored-by, and pushes the branch with a token MergeLoop mints for that one repo and that build. It never pushes over the branch if it changed on GitHub while the build ran: the build is stuck instead, saying so.
  5. MergeLoop's App opens the PR: not a draft, labeled with the repo's label, assigned to you, its body starting with Closes #<issue>.
  6. The daemon lands it, as below.

A build holds a slot from its claim until its PR is open, and again while an agent works a need on the PR. A PR that waits holds none.

Once its PR is open, the daemon is the PR's author in the land loop (next_need), as mergeloop [PR] is for an agent. Review threads, and changes a required reviewer asked for, are worked by the agent in a fresh worktree on the PR's branch: the agent changes files only, and the daemon runs verify, commits as the App's bot with you as Co-authored-by, pushes, then posts the agent's replies in the threads, each naming the pushed commit, and resolves the threads the agent named. When GitHub refuses a reply, a resolve or the read of the threads, the daemon tries again, twice more, without running the agent again or posting a reply twice. After a run that pushed, the daemon waits for MergeLoop to say what the PR needs next. After a run that pushed nothing, it asks again at once: a need still as it was was not settled by the run, and the next run is told so, with the threads still open, since a reply alone closes none. A PR that waits, on the queue or on a human (an approval, a draft, a PR taken out of the queue), runs no agent, and the daemon asks how it stands as often as it heartbeats. An ejected PR is queued again once. When MergeLoop cannot answer for now (it is unreachable, or answers 5xx), the daemon says so and asks again after a pause; only MergeLoop's refusals end a build. A repo renamed while its PR lands is no refusal: the daemon reads the build's task again and goes on under the new name.

The daemon names itself once, in daemon/id in its folder, and holds only the builds it claimed: another daemon of yours, on this machine or another, takes one only once it is given back or goes 30 minutes unheard, as anyone's would.

The config file

mergeloop daemon --help lists the settings. They live in ~/.mergeloop/daemon.toml, or the file --config FILE names; without the file, the defaults hold. An unknown key is an error.

slots = 1                          # builds at once, at least 1
workspace = "~/.mergeloop/daemon"  # the daemon's own folder, new or empty at first: absolute, or ~/...
access = "workspace"               # or "full": see "What an agent may do on your machine"
# deny_read = ["~/.ssh", ...]      # what a build may not read in workspace access: replaces the default list

[builder]
agent = "claude"                   # or "codex": the flags it gets, and how its output reads
command = "claude"                 # default: the agent's name; a wrapper that takes its flags works, such as "mclaude"
# model = "..."                    # default: the CLI's own
# effort = "..."                   # default: the CLI's own
args = []                          # more arguments for every run, after MergeLoop's
timeout_minutes = 60               # the longest one run may take, at least 1

[reviewer]
enabled = true                     # false: no local review
# agent = "codex"                  # default: the other agent when its CLI is on PATH, else (or when command is set) the builder's
# command = "codex"                # default: the agent's name, or, for the builder's own agent, the builder's command and args
# model = "..."                    # its own, not the builder's; default: the CLI's own
# effort = "..."                   # its own; default: the CLI's own
# args = []                        # default: none, or the builder's with the builder's command
timeout_minutes = 60               # the longest one review may take, at least 1

The default deny_read is your MergeLoop session (~/.mergeloop/session) and the places credentials live in a home folder: ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, ~/.git-credentials, ~/.config/gh, ~/.config/gcloud, ~/.azure, ~/.docker/config.json, ~/.kube, ~/.npmrc, ~/.cargo/credentials, ~/.cargo/credentials.toml, ~/.pypirc, ~/.gem/credentials, ~/.codex/auth.json, ~/.claude/.credentials.json. A path that holds the daemon's folder, or lies in it, is an error. The agent CLIs read their own login themselves, outside their sandboxes, so they keep working.

The local reviewer

Between verify and the push, a reviewer reads the change against the issue: a fresh session of the other agent CLI (Codex for a Claude builder, Claude for a Codex one) when it is on your PATH, else of the builder's own. It answers with findings, each at a file and line, or with none. Findings go back to the builder as a new run in the same worktree, verify runs again, and the reviewer reads the change again: at most 3 reviews. Findings left after the third make the build stuck, with them, and nothing is pushed; so does a reviewer that does not answer with its findings.

The PR body's Local review section says who reviewed the change and in how many rounds, or that the local review was turned off on the machine that built it. A change made later for a need on the PR is not reviewed on the machine: MergeLoop's own review reads it on the PR.

The reviewer runs with the builder's access, read denials and environment, and no token of any kind, in a folder of its own (reviews/<build>/, outside the build's): in workspace access it may write only there and in its CLI's temp folder, so it reads the build's worktree and cannot change it. In full access nothing confines it, and what stands is the daemon's check, after every review, that the worktree still holds just the commit it reviewed: a build whose reviewer changed a tracked file, added an unignored one or committed is stuck, with nothing pushed. Writes to ignored files, or outside the worktree, are not caught.

Who the agent acts as

An agent and what it runs never act as you on GitHub or MergeLoop: a reply or a resolved thread from your own login would count as a human's answer to MergeLoop's review. Every run loses GH_TOKEN, GITHUB_TOKEN, MERGELOOP_TOKEN, MERGELOOP_URL, SSH_AUTH_SOCK and the like from your environment; gh gets an empty config folder in the build's folder (GH_CONFIG_DIR), and git no credential helper and no prompt.

  • The builder, the reviewer and every verify command get no token.
  • An agent working a need on the PR gets a token for the build's repo that only reads it and its PRs (contents: read, pull_requests: read), as GH_TOKEN, GITHUB_TOKEN and MERGELOOP_TOKEN, so gh and mergeloop call read as the App's bot. It reads what anyone who can comment on the PR wrote, so it holds nothing that can write.
  • The token that pushes (contents: write, pull_requests: write, for that one repo, for GitHub's hour) stays in the daemon, for its own git and its replies and resolves. The daemon asks for it with mint_build_token and the push scope; MergeLoop mints it only while you hold the build and GitHub says, asked afresh, that you may push. It does not carry GitHub's workflows permission, so a build cannot change the files under .github/workflows: GitHub refuses the push, and the build is stuck with that refusal as its reason. An issue that changes CI is one for a person.

The workspace folder, and how it is cleaned

The daemon's folder, ~/.mergeloop/daemon by default, must be its own. The daemon makes it its own when it first starts there, if the folder is missing or empty, by writing its name in daemon/id. It refuses to start in a folder that has other things in it and no daemon/id, and touches nothing there: give it a new folder instead. It holds:

  • daemon/: its lock (a second daemon on the same folder refuses to start), its name (id), and the process groups its builds run.
  • repos/<owner>/<name>.git: its own clone of each repo it builds in. It never touches your checkouts. When the daemon learns that a repo was renamed, as a PR lands, the clone under the old name is marked (mergeloop-renamed in it) and removed once no build's worktree is in it: at once, or when the last such build ends. Builds go on under the new name, in a clone of that name. A repo renamed while no build of it is landing leaves its old clone, which you may remove while the daemon is stopped.
  • builds/<build>/: a build's folder, its worktree tree/ on its local branch, and its tmp/.
  • reviews/<build>/: the reviewer's folder, made empty for each review.
  • transcripts/<build>/: what the agents printed, kept 7 days after last written.

The agent and each verify command run in a process group of their own, and whatever they leave running is stopped when their run ends; a process that leaves its group (setsid) is not found. A build's folders and local branch are removed when the build ends, however it ends, once its processes are gone. A PR's need gets a worktree only while its agent works, and loses it once the change is pushed: a PR that waits has nothing on disk but its transcripts. On start, the daemon stops what a daemon killed mid-build left running, removes whatever a crash left of builds, gives back the builds without a PR that it still holds, and lands again those with one, once MergeLoop has finished labeling and assigning their PR. It removes only what it knows as a leftover of its own, saying so in one line: a build's or a reviewer's folder of a build it does not hold, and a clone under repos/<owner>/<name>.git that is broken, such as one a crash left before it had its origin, which is made again when a build next needs it. It also removes a renamed repo's clone that no build uses, and a repos/<owner>/<name>.git.gone, which is such a clone a crash left half removed. Anything else of another shape it leaves, saying so. It follows no symlink in its folder: it never makes one there, so a symlink where it keeps a folder of its own stops the start, with a message naming it, and nothing it points at is touched. A lock, a name or a record of process groups that it cannot read stops the start too, naming the path: stopping is safe, deleting is not.

How a build is confined

In workspace access, the daemon passes each CLI its own confinement:

  • Claude Code: --setting-sources user (a repo's .claude/ settings, which a build can write, never loosen it), --permission-mode acceptEdits --add-dir <build folder>, and --settings that turn on its sandbox (refusing to start without one, with no retry outside it, network open) with filesystem.denyRead, a Read allow rule and Read deny rules for its file tools (so they read what its shell may), and permissions.blockWritesOutsideWorkingDirectories.
  • Codex: --skip-git-repo-check (a reviewer's folder is no git repo), --ignore-user-config (your config.toml is not read, as a sandbox_mode in it would replace what follows; your login still is), and a permission profile in -c: read everything, write the build's folder, deny each deny_read path, network on, no approvals.
  • verify commands: sandbox-exec on macOS, bwrap on Linux, writing only the build's folder and reading no deny_read path, nor a symlink to one.

The daemon's own git on a build names the worktree's git dir rather than following its .git, runs no hooks, and in workspace access runs under the same read denials, so nothing a build leaves runs as the daemon. It commits a build's worktree only while it is the folder the daemon made: a build that puts a link or another folder in its place is stuck, and nothing is pushed.

How a build ends

  • Merged. The PR merged, by the queue or outside it. The build shows as merged until its issue closes, as the PR's Closes #<issue> does.
  • Stuck. The agent gave up, verify still failed after its fix, the reviewer still had findings after 3 rounds, the PR was ejected a second time or still needed its author after 10 runs of the agent, GitHub kept refusing the daemon's answer, a person closed the PR without merging it, or anything else went wrong. The daemon says why on the issue, and the Builds page shows it in full. To try again, take the label off the issue and put it back: a stuck build with an open PR goes back to landing it, and one whose PR was closed is built anew over the old branch.
  • Given back. Ctrl-C gives back the builds without a PR: they are tasks again at once. It keeps those with one, which the daemon lands again when started; another daemon takes one over once it goes 30 minutes unheard. A build is given back too when GitHub says you may no longer push.
  • Dropped. The issue was closed or lost its label before the build had a PR. A build with a PR is never dropped this way: closing its issue is what merging it does.

Whose PR a built PR is

GitHub has the App's bot as the author of a built PR. Everywhere MergeLoop asks whose PR it is, it is the PR of the developer whose daemon holds its build at that moment: the seat it takes when it joins a private repo's queue, and the name it is kept under in the history, the people view and the queue's events. A developer has one seat whether their PRs are built or their own. When a stale build is taken over, the seat already taken when the PR joined stays; the next count made, such as its leaving the queue, is the new holder's. A seat is kept by GitHub login, as for every PR, and the daemon's login is the one from its sign-in: a developer who renames their GitHub account, even only its capitalization, runs mergeloop login again, or their built PRs take a seat under the old name beside the one their own PRs take.

Dark merges

A dark merge is one that no human saw. The build lane does not decide this; two gates do, both outside the daemon: MergeLoop's review, with its confidence bars and the kinds it always asks a human about, and GitHub's rules for the branch, which the repo's maintainers set. What must never merge dark is a human decision, made as a required approval.

The App's bot is the author of every built PR, so the developer whose daemon built it is not: they can approve it, and MergeLoop counts their answer to a question its review asks. GitHub does not let an author approve its own PR, so MergeLoop never approves a PR it built. How dark a built PR gets depends on the repo's rules:

How the repo is set up An ordinary change A path that must never merge dark
Rules by path. No approval is needed in general; sensitive paths need their code owner. Dark. It merges once MergeLoop's review lets it on. A human. The code owner approves; that can be the developer, if they are one.
Every PR needs one approval. The common default. One click. The developer approves their daemon's PR. Never dark. A human. The code owner approves.

A PR a person opens can merge dark under "every PR needs one approval", since MergeLoop approves it once its review passes; a built PR cannot. Letting MergeLoop bypass that rule for built PRs, with the sensitive paths in a second ruleset with no bypass, is not built: GitHub's documentation does not say whether that second ruleset still holds against the bypass, or how MergeLoop could tell before it merges. docs/build-bypass.md says what it does say, and the check on a scratch repo that would settle it. Making the App a bypass actor changes nothing today: MergeLoop never asks GitHub to use a bypass.

How jobs are isolated

A rebase job runs the repo's code (the verify commands) and an agent with a shell. MergeLoop treats it as untrusted:

  • The orchestrator holds the GitHub App key and the queue. It never runs repo code.
  • Each job runs mergepatrol job in its own container, from the job image. It gets a GitHub token that can only read the one repo, and revokes it once it has fetched the repo. It returns a git bundle.
  • The workspace's model API keys and ChatGPT login stay in the orchestrator, which renews the login. A job calls its provider's API through the orchestrator's proxy, at /anthropic for Claude Code or /openai for Codex, with a token that works only while the job runs, and for a set number of requests.
  • The orchestrator checks the bundle before it publishes: the result must sit on the base branch, and change no file that the PR did not change.

In production the job containers use gVisor (runsc) on a network that cannot reach the cloud metadata server, private ranges, or the host. deploy/sandbox-host.sh sets that up on a Linux VM. Then set:

Variable Default What it does
MERGEPATROL_EXECUTOR local docker runs each job in a container. agent-sandbox runs it in a GKE sandbox: see On GCP. local runs it as a process, without isolation, for development
MERGEPATROL_JOB_IMAGE mergepatrol-job:latest The job image (docker build --target job)
MERGEPATROL_JOB_RUNTIME Docker's default runsc for gVisor
MERGEPATROL_JOB_NETWORK Docker's default mergepatrol-jobs, from deploy/sandbox-host.sh
MERGEPATROL_JOB_RESOLV_CONF Docker's default A file on the Docker host, mounted as the jobs' /etc/resolv.conf. /etc/mergepatrol/job-resolv.conf on the sandbox network
MERGEPATROL_JOB_PROXY_URL MERGEPATROL_PUBLIC_URL Where jobs reach the orchestrator: its model API proxy, and a GKE sandbox's link. http://10.213.0.1:8081 on the sandbox network
MERGEPATROL_JOB_PROXY_BIND None A second listener that serves only what jobs use, for jobs that cannot reach the dashboard's. 0.0.0.0:8081 in compose.yml
MERGEPATROL_JOB_MEMORY 4g Memory limit per job
MERGEPATROL_JOB_CPUS 2 CPU limit per job

The job image has git, the Claude and Codex CLIs, Rust, Go, Python with uv, and Node with pnpm and Bun, for the verify commands and for the agent, which regenerates a generated file that conflicts with the repo's own tools.

No release has been published yet, so for now build both images from source with docker compose up --build. Once releases start, each one publishes both images, tagged with its version and latest: ghcr.io/agent-labs-dev/mergeloop, the orchestrator, and ghcr.io/agent-labs-dev/mergeloop-job. To run a release instead of building, set MERGEPATROL_JOB_IMAGE=ghcr.io/agent-labs-dev/mergeloop-job:<version>.

On GCP

deploy/gcp/bootstrap.sh sets up one environment in a GCP project with billing linked: the GKE Autopilot cluster mergepatrol, Cloud SQL Postgres, and a load balancer for the public URL. It deploys with deploy/gcp/cloudbuild.yaml, which runs deploy/gcp/deploy.sh. The manifests are under deploy/gcp/k8s.

The orchestrator runs as the Deployment mergepatrol, one instance, with Cloud SQL through a proxy sidecar and its secrets from Secret Manager. Only the instance that holds a lock in Postgres runs the queues, so the new instance of a deploy waits until the old one has stopped. On SIGTERM, an instance lets go of the lock at once.

Each job runs in its own gVisor sandbox, through Agent Sandbox: the orchestrator claims one from the warm pool mergepatrol-job, which keeps one sandbox ready, so a job starts in about a second. Jobs past the first start cold, on a new node, in 1 to 2.5 minutes. A sandbox has no service account and no DNS. Its network policy lets it reach two things: the orchestrator's job port, and the egress proxy mergepatrol-egress. It can't reach the metadata server, the rest of the cluster, the VPC, or the internet directly. The egress proxy is Squid, at 34.118.224.100:3128, set as the sandbox's HTTPS_PROXY. It opens tunnels to port 443 of the hosts in deploy/gcp/k8s/squid.conf, and refuses every other host:

  • GitHub, to fetch the repo and revoke the job's token.
  • The package registries the verify commands use: npm and Yarn, PyPI, the Go module proxy and its bucket, crates.io, and rustup's toolchains.

A job that needs another host fails until the host is added there. The proxy logs every tunnel it opens or refuses (kubectl -n mergepatrol-jobs logs -l app=mergepatrol-egress). The allowlist goes by host name. So it doesn't stop a job that brings its own credentials from pushing to GitHub or publishing to a registry. It also doesn't stop a job from writing to a bucket that anyone can write to on storage.googleapis.com, where the Go proxy keeps large modules. CONNECT is checked against the requested hostname only; because the proxy does not intercept TLS or inspect SNI, a CDN can serve another hostname through an allowed tunnel. Treat the proxy as a coarse egress allowlist, not as end-to-end hostname identity enforcement.

The orchestrator hands the sandbox its link, http://<orchestrator pod IP>:8081/jobs/<token>, over HTTP, since a claim that sets env would skip the warm pool. With that link, the job fetches its spec once, uploads its result in chunks, and reports that it is done.

This is the hosted MergeLoop at https://mergeloop.ai. It runs the public App Merge Loop, which any account can install; each workspace brings its own Anthropic or OpenAI API key. deploy/gcp/hosted-app.sh creates the App once and stores its credentials in Secret Manager.

Variable What it is
MERGEPATROL_SANDBOX_NAMESPACE Where the jobs' sandboxes run, with MERGEPATROL_EXECUTOR=agent-sandbox. mergepatrol-jobs by default
MERGEPATROL_SANDBOX_WARM_POOL The SandboxWarmPool that sandboxes are claimed from. mergepatrol-job by default
MERGEPATROL_POSTHOG_KEY The PostHog project key. Turns on product analytics (below)
MERGEPATROL_POSTHOG_HOST The PostHog host. https://us.i.posthog.com by default

Billing

Billing runs through Stripe, and is off unless the three MERGEPATROL_STRIPE_* variables below are set. In Stripe, create:

  1. A product, with a recurring price of $15 a month per unit: MERGEPATROL_STRIPE_PRICE. MergeLoop keeps each subscription's quantity at the workspace's seats.
  2. A webhook endpoint at <public URL>/webhooks/stripe, for checkout.session.completed and customer.subscription.created, .updated and .deleted: its signing secret is MERGEPATROL_STRIPE_WEBHOOK_SECRET.
  3. The customer portal's settings, where a customer adds a card, sees invoices, or cancels.

A workspace's first subscription starts with Stripe's trial, without a card. One that has no card when the trial ends is cancelled.

Variable What it is
MERGEPATROL_STRIPE_SECRET_KEY A secret or restricted key: Checkout sessions, customer portal sessions, and subscriptions (write)
MERGEPATROL_STRIPE_WEBHOOK_SECRET The webhook endpoint's signing secret, whsec_…
MERGEPATROL_STRIPE_PRICE The price, price_…

Analytics

With MERGEPATROL_POSTHOG_KEY, the hosted MergeLoop sends product analytics to PostHog. Without it, as when self-hosted, it sends nothing, and the dashboard does not load PostHog.

  • A person is a GitHub login. The dashboard identifies the signed-in user, and the server sends signed in.
  • A workspace group is an installation of the App, keyed by its installation ID, with the account's name. The dashboard groups what the user does under the workspace in view.
  • Each queue event goes to its PR's author and workspace as pr <kind>, such as pr merged or pr ejected, with the repo, trunk and PR number. When a PR leaves the queue, the event also has queue_seconds, the seconds in each step (waiting_seconds, held_seconds, rebasing_seconds, checks_seconds, fixing_seconds), and, for pr ejected, the reason: fork, rebase-failed, checks-failed, fix-failed, base-moved, merge-rejected, checks-timed-out or checks-missing.
  • Installing the App sends app installed, for the person who installed it, and uninstalling it app uninstalled.
  • The dashboard sends api key set and api key removed, with the provider, and repo config proposed.
  • Before sign-in, the landing page and the /blog articles send PostHog's $pageview and autocaptured clicks under an anonymous id, with no person profile. The articles load PostHog's script themselves, as they are plain HTML outside the dashboard. A reader keeps the same id from an article to the landing page, and signing in joins it to their login.

Crates

Crate What it does
core The queue and its state machine. Pure logic, no I/O
github GitHub App auth, the REST and GraphQL calls, and publishing commits through the Git Data API
git Local git: fetch, worktrees, rebase
resolver The Resolver trait, and its implementations: Claude Code for Anthropic, Codex for OpenAI
executor Runs a rebase job: as a local process, or in a container. The job protocol
store The Store trait, Postgres, and the encrypted secrets. Tests need the dev Postgres from compose.dev.yml
web The HTTP server: JSON API and the dashboard
analytics Product analytics in PostHog, for the hosted MergeLoop
mergepatrol The binary: the orchestrator, and mergepatrol job for the sandbox
cli mergeloop, the command an agent lands a PR with: a client of the MCP server

Compared to GitHub's merge queue

GitHub's merge queue also tests PRs together before they merge. What MergeLoop adds:

MergeLoop
A PR that conflicts with its base An agent resolves the conflict, and the PR stays in the queue
A required check that fails An agent commits a fix on the PR, up to fix_ci.attempts times, before the PR is ejected
A batch that fails Half of it is tested next, and so on down to the one PR that fails. The rest merge
Stacked PRs A gh stack stack queues and merges as one item
CI Runs on the repo's pull_request workflows, on a draft PR per batch. No merge_group trigger to add
Queueing a PR A label, so people and coding agents queue the same way

For Mergify, Graphite, Aviator and Trunk as well, see mergeloop.ai/compare.

Contributing

See CONTRIBUTING.md. Report vulnerabilities privately, as SECURITY.md describes.

License

Apache-2.0

About

Merge queue for GitHub that resolves rebase conflicts with an agent. Hosted at mergepatrol.ai, or self-host it.

Topics

Resources

Contributing

Security policy

Stars

9 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages