Mergepatrol

Configuration: .mergepatrol/mergepatrol.yml

Repo settings

Each repo sets its queue in .mergepatrol/mergepatrol.yml on its default branch. Mergepatrol reads the file from there, so a PR cannot change its own settings. A setting the file leaves out takes the instance’s default: on a self-hosted Mergepatrol, the MERGEPATROL_* variables in Environment variables.

version: 1
label: mergepatrol
batch_size: 8
resolver:
  provider: anthropic   # or openai
  model: claude-opus-5-5
  effort: medium        # low, medium, high, xhigh or max
verify:
  - cargo check
fix_ci:
  enabled: true    # an agent fixes failed required checks
  attempts: 2      # 1 to 5 fixes, 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 clear a kind alone: 50 to 100, or always_ask
    security: always_ask
    dependencies: 95

The resolver 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 default must set its model too.

The verify commands run after an agent resolution or fix, before the publish.

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 .mergepatrol/. 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. Mergepatrol 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 Repos override the file, until you choose Follow the config file.

The dashboard edits the file through PRs. Set up opens a PR that adds the file with the defaults, and the mergepatrol agent skill at .agents/skills/mergepatrol/SKILL.md and .claude/skills/mergepatrol/SKILL.md, so coding agents in the repo queue their PRs rather than merge them. Settings opens one that changes the file. Both come from the branch mergepatrol/config: a second change updates the open PR. The queue uses the new settings once the PR merges.

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

Docs