pictured above: the mergatron
Generate an AI auto-triage/fix/merge configuration for GitHub. The idea is that the repos run themselves, exactly as you intend.
It has three presets which may make it easier to use, these are:
- conservative (bot just reviews)
- normal (bot reviews everything, automerges small things)
- mayhem (bot merges its own code)
Each mode gains capability over the one before it:
Tip
All modes are fully adjustable and tunable thru script or agent setup.
Option A. Generate files entirely with an agent
Run setup.sh through your agent, from this directory, for your repo e.g.:
Read CUSTOMIZE.md and walk me through setting up mergatron for
hackingmaterials/my_repoOption B. Generate manually and refine with an agent/manually
Run
./setup.sh --repo hackingmaterials/my_repo --mode normal --maintainer @someonesetup.sh --help will tell you more. Important parameters are
--repo OWNER/REPO(required): Example,hackingmaterials/matminer.--mode: A preset list of options and scripts that can be set easily, refined later. Values areconservative,normal, andmayhem.--maintainer: Maintainers the bot tags when it escalates. The first is the default; repeat the option to list more.
The files go to output/REPO/.github/.
Either:
- have your agent guide you through
CUSTOMIZE.md, using the promptsetup.shprints at the end - edit
output/REPO/.github/mergatron_rules.md(andmergatron.conffor settings) yourself
Copy the contents of output/REPO/.github/ into your repo's .github/ and
merge to main. Nothing runs until it's there.
If the API key isn't set yet: gh secret set ANTHROPIC_API_KEY -R OWNER/REPO
Run /install-github-app in Claude Code, from your repo, so the bot posts as
claude[bot]. Skip its own workflows.
This configurator creates
- Workflows for GitHub Actions
- deterministic gates (scripts) which prevent the agent from doing crazy stuff (e.g., merging or committing what the mode doesn't allow).
- agent behavior in an md file.
- settings, including the mode, in
mergatron.conf.
The agent takes code-changing action (merges and commits) through the scripts.
The rest of the agent's behavior, such as when it takes action, how, and what it
says, is set in the md file. Change the mode and settings later in
mergatron.conf.
Defaults per mode. Adjust in mergatron.conf.
| PR: review, label, escalate | ✅ | ✅ | ✅ |
| PR: merge (docs) | ❌ | ✅ | ✅ |
| PR: merge (dependency upgrades) | ❌ | ✅ | ✅ |
| PR: merge (small, tested) | ❌ | ✅ | ✅ |
| PR: merge (anything passing CI + review) | ❌ | ❌ | ✅ |
| PR: merge (outside contributors) | ❌ | ✅ | ✅ |
| PR: merge (own fixes) | ❌ | ❌ | ✅ |
PR: merge (pyproject.toml) |
❌ | ✅ | ✅ |
PR: merge (.github/, not workflows) |
❌ | ❌ | ✅ |
| Issue: close (by merging own fix) | ❌ | ❌ | ✅ |
Write access only.
| PR: answer, review | ✅ | ✅ | ✅ |
| Issue: answer, investigate | ✅ | ✅ | ✅ |
| PR: commit (same repo) | ❌ | ✅ | ✅ |
| PR: commit (fork) | ❌ | ❌ | ❌ |
| Issue: open fix PR | ❌ | draft | ready |
| PRs: sweep now | ✅ | ✅ | ✅ |
| Enforced by | |
|---|---|
| PR: merge (failing CI) | script |
| PR: merge (protected files) | script |
| PR: commit (default branch) | script |
| PR: approve | rules |
| PR: close | rules |
| Fix: add dependencies | rules |
| Run code or tests | workflow |
| Obey non-maintainers | workflow |
