The sweep engine for bot pull requests.
Drains a team's queue of
Renovate,
Align files, Herald and
Dependabot
pull requests by codified rules, as the person who runs it.
marge sweep --team <name> reads the team's repositories from giantswarm/github, finds every open bot PR, approves and squash-merges the eligible green ones, labels each PR with its classification, writes its evidence on the PR and prints the outcomes. Nothing it does needs a model. The interactive marge [query] command and the MCP server run the same engine.
Download the binary for your platform (Linux, macOS, Windows; amd64 and arm64) from the releases page: the assets are named marge-<os>-<arch>, each next to its cosign signature bundle (marge-<os>-<arch>.bundle). Releases are built and signed by the repository's CircleCI pipeline; marge self-update installs a newer release only after that bundle verifies.
marge moved here from a personal namespace, and its release pipeline moved from GitHub Actions to CircleCI. Binaries up to v0.8.1 verify release signatures against the former pipeline and refuse releases built here, so
marge self-updatecannot carry them across. Install once from the releases page above; from then onself-updateworks again.
go install github.com/giantswarm/marge@latestOr clone and build locally (make build stamps the version with gitsemver; make install puts the binary into $(go env GOPATH)/bin):
git clone https://github.com/giantswarm/marge.git
cd marge
make installThe marge Helm chart in the giantswarm catalog runs marge serve over the MCP Streamable HTTP transport behind a ClusterIP Service. The server pod holds no GitHub credential of its own: it acts with the bearer token each call carries. The chart does not register the server with muster. That is the platform's job, declared next to the muster's other servers: an MCPServer that points at the Service URL, auth.type: oauth, and the GitHub authorization server pinned with the client the muster's other GitHub-backed servers share. muster keeps one client and one grant per GitHub issuer, so a person signed in to one of them is signed in to marge, and marge acts with that person's own GitHub rights. The sweep App backs the scheduled runs only. See helm/marge/README.md for every value.
A freshly registered server reports Auth Required until the person completes core_auth_login in muster, then Connected. With grantScope: subject the grant is filed under the person, so every later session reuses it without a second consent, until they sign out of this server.
Marge needs a GitHub token and looks for one in this order:
- the
GITHUB_TOKENenvironment variable - the
GH_TOKENenvironment variable - the GitHub CLI's active login (
gh auth token)
If you are logged in with gh auth login, no further setup is needed. Otherwise export a personal access token:
export GITHUB_TOKEN="ghp_..."A scheduled run uses none of these. It authenticates as the sweep GitHub App and mints an installation token per repository; see docs/github-app.md.
Classic token: needs the repo scope.
Fine-grained token: select the repositories you want marge to manage, then grant these permissions:
| Permission | Access | Why |
|---|---|---|
| Pull requests | Read & write | Approve and merge PRs |
| Issues | Read & write | Write the marge/<class> label and the evidence comments |
| Checks | Read | Read check runs |
| Commit statuses | Read | Read combined commit status |
| Metadata | Read | Required by default |
| Contents | Read & write | Compare a PR with its base (stale classification, marker fingerprints); update a PR branch from its base |
| Administration | Read | Read the base branch's required status checks. Without it marge approves and tries the merge, GitHub enforces the checks, and a refusal for a check reason is reported as Waiting for checks |
The token needs read access to the repository that holds the team files and the policy files: giantswarm/github, or the owner/repo that MARGE_TEAM_FILE_REPO names.
Optionally, a CircleCI API token lets marge inspect builds of private CircleCI projects and retry auto-cancelled builds (see Cancelled builds). marge reads CIRCLECI_CLI_TOKEN or the CircleCI CLI's own config, ~/.circleci/cli.yml, and sends it as the Circle-Token header. Public projects need no token.
When run without a query, marge enters interactive mode: it fetches all open bot PRs requesting your review and lets you pick a group to process.
When run with a query (e.g. a repo name or dependency), it filters PRs directly and processes them.
| Flag | Short | Default | Description |
|---|---|---|---|
--dry-run |
false |
Show what would be done without making changes | |
--watch |
-w |
false |
Keep polling for new PRs every 60 seconds |
--grouping |
repo |
Group by repo or dependency |
|
--actions |
(all but rescue) |
Comma-separated sweep steps to run, in fixed order: classify, changelog, approve, merge, refresh, retry, remedy, rescue, mark (see Actions); rescue needs the team scope of marge sweep |
|
--org |
Limit to repos owned by this org or user | ||
--repos-file |
File with org/repo entries (one per line; blank lines and # comments are ignored) to scan for bot PRs instead of searching GitHub. A query then keeps only the listed repos whose org/repo contains it (case-insensitive) |
||
--no-tui |
false |
Disable the live table; print plain-text results instead | |
--merge-auto |
false |
Also merge PRs that have auto-merge enabled (by default the merge itself is left to GitHub) | |
--suite-limit |
2 |
How many e2e suites one pass may start through comment-command; 0 starts none |
|
--security-patterns |
(built-in) | Add to the built-in security check pattern list (see below) | |
--rules-repo |
giantswarm/marge |
Repository the rule catalogue is read from, as owner/name |
|
--rules-ref |
main |
Branch the rule catalogue is read from | |
--rules-path |
Read the catalogue from this directory instead of the repository |
marge touches PRs authored by four bots and nothing else: renovate[bot] (Renovate), giantswarm-align-files[bot] (Align files), heraldbot[bot] (Herald, nancy-fixer's security remediation PRs) and dependabot[bot], plus one more kind, the upstream chart sync (upstream-sync): the PR that the sync-from-upstream workflow of a vendored-chart repository opens as giantswarm-release[bot], labelled automated-update. A repository whose workflows are not regenerated yet still opens it as taylorbot; that login counts only from its own account id, so an account that takes the login after taylorbot is deleted is a person. A sync PR's body names only the versions it syncs to, so marge reads the size of the sync from the version: and appVersion: lines that its diff changes in each Chart.yaml. A sync PR merges only where its team's policy file opts in, for example updateTypes: {upstream-sync: [patch, minor]}; under the company defaults every sync PR waits for a person. A self-hosted Renovate that runs under the account owning a personal repository opens its PRs as that account; such a PR is Renovate's when the owner authored it from a renovate/ branch and its body carries Renovate's signature, and marge merges it without an approval, which GitHub refuses on one's own PR. Any other PR by a person, the caller's own included, is reported as Untrusted author and never approved or merged. There is no flag to widen that set.
In giantswarm/github, an Align files PR whose head branch starts with reposetup/ is a team-file PR of the repository reconciler. Its gate is that repository's own team-file classification, so the sweep reports it as Skipped with that reason and writes nothing to it, no label included. The reconciler's reposetup/ PRs in any other repository are swept like every Align files PR.
A green PR merges when the resolved sweep policy says its kind and update size are eligible. The company defaults are: Align files and Herald PRs always; Renovate and Dependabot patch, minor, digest, pin and lockfile updates. A major update, or one whose size marge cannot read, is Held for a person. So is a PR whose body asks for a proof before merging, an unticked task list item under a line that says "before merging" (or one that says it itself), whatever the caller and with or without --merge-auto: its entry reads held: needs proof and names the open item. Green CI is not that proof; the PR merges once every item is ticked. The update size comes from the versions Dependabot writes in the title (or, for a group, per dependency in the body) and Renovate writes in the body's Change column.
A team declares its own appetite for sweeps in giantswarm/github, in files the team owns. marge reads them from the default branch at the start of every sweep, so a change takes effect on the next run.
| File | Holds | Owned by |
|---|---|---|
bot-prs-sweep/default.yaml |
the company defaults | Bumblebee, in CODEOWNERS |
bot-prs-sweep/team-<name>.yaml |
one team's deviations | that team, in CODEOWNERS: a new team file adds its own line, or the directory line leaves it with Bumblebee |
botPRsSweep on a repository entry of repositories/team-<name>.yaml |
one repository's exception | that team |
teams/team-<name>.yaml |
the team's Slack channels, which the summary is posted to | that team |
The policy files say what may merge, and nothing about when a team is swept. Each team has its own CronJob in the chart, which sweeps that team on its own cadence and is suspended on its own. A team without a policy file is swept under the company defaults.
# bot-prs-sweep/team-bumblebee.yaml
summary: true
updateTypes:
renovate: [patch, minor]
rescue:
enabled: false
timeout: 20m # per rescue
weekly: 5 # rescues per week
budget:
perRescue: 3.00 # US dollars, declared
weekly: 15.00 # US dollars, declared
confirm: per-pr
concurrency:
perTeam: 5
perRepo: 1
modelConfig: default-model-config
changelog:
path: CHANGELOG.md
heading: "## [Unreleased]"
section: "### Changed"
template: "- Update {{ .Dependency }}{{ if .From }} from {{ .From }}{{ end }} to {{ .To }} ({{ .PR }})"summary switches the team's summary on; the company defaults post none. The summary goes to the notices channel of the team's channel file, the one place in giantswarm/github that names a team's Slack channels for every automation that messages the team:
# teams/team-<name>.yaml
notices:
id: C0123456789 # the channel's Slack ID, which the summary is delivered to
name: standup-example # the channel's name, shown and never used for deliverymarge reads the file only for a team whose policy sets summary: true, strictly like a policy file, and nothing else in it: asks, the channel for messages that wait for the team, is known and not read. A team whose policy sets summary: true and that has no channel file fails its post: its sweep runs, and its outcome names the missing file.
The summary reaches the channel through klaus-gateway's team-notice endpoint (POST /notices): the gateway holds the Slack app and the workspace credential, and a scheduled run authenticates with the projected ServiceAccount token its pod already carries, so marge holds no Slack token. The chart's notices.gatewayURL names the gateway; without it, and for a team whose policy posts no summary, the run does its work, posts nothing and says so in its log. A post the gateway answers with a 5xx, or does not answer in time, is tried four times with a doubling wait; one that still fails is logged as an error with the summary printed to the run's log, and the run succeeds, since its outcome is the PR actions it took. A post the gateway refuses with a 4xx (a token or channel it does not accept) is not retried and fails the run, since every later run would repeat it.
Every key is optional and an absent key keeps what the file before it said. updateTypes replaces the list of the kinds it names; the known update types are major, minor, patch, digest, pin, lockfile and none, and an update whose size marge could not read can never be declared eligible. An empty list is a list: renovate: [] merges no Renovate PR at all.
enabled lets a run with the rescue step hand the team's PRs over for rescue, and weekly bounds how many: the step counts the rescue markers written on the team's PRs in the last seven days, whatever their outcome, and hands over no more than what is left. timeout and the two budget figures are declared and not applied: marge does not stop a run at a deadline or at a cost, and the platform bounds no turn by a budget. Every outcome records rescues_dispatched: true and budget_enforced: false, and a sweep whose policy switches the rescues on names every bound it does not apply on stderr. The cost a rescue reports is written on its marker.
changelog is the entry a bot PR earns, in the repositories that still cut their release from the changelog file. A repository with a cliff.toml generates its release notes from its commits, so the update is published on the release page already and no entry is written; marge reads the repository and refuses it with that reason. The sweep's changelog step writes the entry once the checks are green and before it approves anything, and that PR then waits for the CI the commit started; the next sweep classifies the new head and merges it. enabled is the switch and is true. A team that does not want its bot PRs to carry an entry sets enabled: false in its own file, and a repository that keeps no changelog file costs the sweep one read and nothing else. A PR that already carries the line is left alone, so a team does not stall on the same PR every day, and a repository with no such file is decided exactly as it would have been: a changelog is a courtesy, never a guard. The changelog tool writes on demand whatever enabled says. path is the file, heading and section say where in it the entry goes, and template is the line, a Go text template over Dependency, From, To, PR, Repository, Kind and UpdateType. From is empty when the title names only the version the update moves to. A template that does not parse, or that names a value the list does not carry, is an error: a team reads back the line it wrote. The section is created under the heading when the file does not carry it, and the heading under the file's title when it carries neither. The commit is authored by the marge App (329428426+giantswarm-marge[bot]@users.noreply.github.com) whatever token the sweep runs under, and committed by that token's identity: Renovate treats a branch whose last commit has any author outside its gitIgnoredAuthors as a person's, stops rebasing it and never closes it, and the devctl-generated renovate.json5 ignores that address.
concurrency has a ceiling marge owns: perTeam reaches 20, perRepo reaches 5, and the two multiply to at most 20 PRs in flight. GitHub answers a burst of writes with a secondary rate limit, so a policy that declares more is an error rather than a sweep that fails halfway. The product is checked on the resolved policy, so perTeam: 20 in a team file is an error when the company file already raised perRepo. bot-prs-sweep/policy.schema.json checks each key against its own range; JSON Schema cannot multiply, so the pair is marge's to refuse.
The ceiling is the writes'. Every run reads 15 repositories and 4 PRs per repository at once, or the policy's bounds where they are wider: a read moves no branch and posts no comment. Its writes keep the ceiling: no more than the policy's product in flight across the run, whatever they are (a label, a comment, an approval, a merge, an updated branch), and no more than perRepo merges at once in one repository. A PR read beside a sibling that merged before it is read again before its own merge, and decided as it would have been, processed after that sibling.
A base branch's rules are read from its rulesets and from its classic protection. A token without the administration permission may read the rulesets but not the classic protection, and GitHub refuses it on every repository alike ("Resource not accessible by integration"), so the sweep's first read of classic protection answers for the whole run and the rest are not sent; a refusal for want of the admin role is that repository's own.
A refusal for rate reaches marge as a 403, the same status GitHub answers for a protection the caller may not read. The two are told apart by what the answer carries: a rate refusal names the wait, in Retry-After or in the reset time beside an exhausted quota. Every client of the process shares one transport, which waits the time GitHub named and sends the request again, up to three times. While it waits, every other call on the same token waits with it: a refusal is about the token, not about the request, so letting the rest keep sending is what earned it. A call on another token, which is another person in marge serve, goes on; the App's tokens of one installation share one wait, because they spend one limit. A refusal that outlives the retries reaches the caller and is reported. The read path is where this matters: a refresh of four teams classifies 60 PRs per team on one caller token.
A request that hears no answer for 30 seconds is stuck, not slow: GitHub answers in a few seconds. A stuck read is sent again, up to twice, and then reported as the timeout it is; a stuck write is reported at once and never sent again, because it may have been performed. Without the bound one stuck connection held its PR, and its repository's slot, for as long as the connection stayed open.
A wait longer than a minute is a spent token: a primary limit that resets up to an hour away, or a secondary one that asks for as long. Every later call on the token would be refused as well, and a refused read is no evidence, so the run stops there. The PRs it had decided keep their outcome; the others are reported under not_reached and keep the label they had, and the result carries rate_limit.reset_at. Before it reads any PR a run checks the token's budget (GET /rate_limit, which GitHub does not count) against the fewest requests it spends, three per PR and one per repository, and is refused when the token has fewer left. Both refusals, and a spent token met before the first PR, read GitHub rate limit ...; it resets at <RFC 3339 time>, so a caller tells them apart from other failures and knows when to try again.
A repository entry deviates under botPRsSweep, with three keys that only narrow:
# repositories/team-bumblebee.yaml
- name: marge
componentType: cli
botPRsSweep:
enabled: false # no PR of this repository is touched, not even labelled
- name: muster
componentType: service
botPRsSweep:
updateTypes: [patch] # intersected with the team's Renovate and Dependabot lists
rescue: falseupdateTypes here reaches Renovate and Dependabot only. An Align files or Herald PR names no version, so restricting the update sizes of one repository does not stop those two kinds from merging.
An exception that tries to switch the rescues back on where the team switched them off is an error, and so is an update type the team merges for no kind. A widening is refused, never silently narrowed. none is refused here too: it belongs to Align files and Herald, which an exception does not reach, so a list that names it would read as a restriction and switch every Renovate and Dependabot merge off. enabled has no team-level counterpart: a repository is the only place the sweep itself is switched off.
giantswarm/github validates both policy files against bot-prs-sweep/policy.schema.json on every pull request, so a misspelled key fails there and not on the next sweep.
A file marge cannot read stops the sweep and names the file and the key: a misspelled key, a second YAML document, an unknown bot PR kind or update type, a timeout that is not a duration, a negative cap, a confirmation that is neither per-pr nor per-sweep. Falling back to the defaults would sweep a team's repositories under a policy the team never wrote. A file that is simply absent is not an error: the company defaults apply and the outcome names the files that were read.
The policy each PR was decided under is on its outcome entry, with the list of files that produced it, so every decision can be explained after the fact. --output json and the MCP sweep tool carry it as the policy object.
Each guard is enforced by the engine and covered by a scenario test; none has an override flag.
- Required checks. The base branch's required status checks are read from its protection. A required context that is pending, or that nobody reported, is a wait (
Waiting for checks), never a bypass, also when every red check on the head is pre-existing. A merge GitHub refuses for a check reason is a wait too. - Red non-required check. A failing check that is not required blocks the merge when the same check is green on the base head, or never ran there. When it is red on the base head too the failure is pre-existing: the PR merges and the check is named in the detail and in an evidence comment.
- Security check. A failing check whose name matches the security pattern list is never merged past, even when it is red on the base head too. The PR gets a
security-blockedevidence comment and is never handed over for rescue. - Auto-merge. A PR with GitHub auto-merge enabled is classified, held or approved like any other, and then left to GitHub for the merge itself. GitHub fires auto-merge only once every requirement is met and does nothing to meet one, so the sweep still approves it and still updates a branch behind its base. A failing required check classifies the PR on the check, not on auto-merge. The
auto-mergeoutcome is counted apart frommerged, because nothing merged yet. - Review rule. A green PR that GitHub refuses to merge after marge's approval is
Awaiting approval. marge never merges as an admin and never touchesenforce_admins. - Strict protection. A green PR behind its base is brought up to date with Update branch and merges on a later sweep, once its checks ran on the new head.
A guard that refuses a merge for a repository reason refuses it on every sweep, and the PRs count as waiting run after run. The sweep therefore reports the setting itself, under findings in the JSON output and as one line per cause in the team's summary. It changes nothing else: the same PRs are refused for the same reasons, and the fix belongs to the repository.
| Cause | What the sweep saw | What fixes it |
|---|---|---|
strict_protection |
the base branch requires an up-to-date branch, so every merge puts the siblings behind their base and the repository merges one PR per run | a second daily run |
code_owner_review |
the base branch sets require_code_owner_reviews, which the sweep's own approval never satisfies |
the sweep App in CODEOWNERS, or the rule dropped |
silent_required_context |
a required context reported nothing, on a head whose other checks settled more than seven days ago, so no run will report it | the context removed from the protection, or the workflow that produces it |
archived |
GitHub reports the repository archived, so it is read-only, while its team-file entry still declares it active; its PRs are skipped and receive no write |
the entry's lifecycle set to archived |
A finding is recorded on the PR the setting holds, and the summary groups the findings by cause with a count of the PRs and the repositories: a team sweeps up to 78 repositories, and one line per repository does not reach a reader. The JSON output carries every repository, with the count of each and the required context that never reported.
Every PR the sweep touched carries exactly one marge/<class> label, replaced on each sweep: merged, auto-merge, eligible, pending, action-required, held, awaiting-approval, security, stale, conflict, ci-unavailable, skipped. Labels are display only; no guard reads them back. A label marge may not write is a note on the entry, never a different outcome. A bot-prs-sweep/<class> label from the earlier namespace is removed on the next sweep that touches the PR.
An action marge performed, or a guard decision a person needs to see, is written once as an evidence comment: update-branch, retry, merged-past-red-check, awaiting-approval, security-blocked, held. The held comment names the update type that waits and the policy files that decided it, or the open proof item, which the label does not carry. Evidence is an ai-rescue marker with "kind":"evidence" and "tool":"marge", so it carries the head SHA and the diff fingerprint. A second sweep on the same change writes nothing: the fingerprint, not the SHA, decides, so a Renovate rebase does not repeat the comment.
--actions runs a subset of the sweep steps, always in this order: classify (read the PR, its checks and markers, decide the state, write the label; always runs), changelog (commit the team's changelog entry on a PR whose checks are green, before anything is approved, unless the team's policy switches it off or the repository generates its release notes from its commits; the PR then waits for the CI that commit started, and the next sweep merges it), approve, merge, refresh (update stale branches from their base), retry (re-run auto-cancelled CircleCI builds on the same head, and once per head a finished CircleCI workflow whose statuses never reached GitHub), remedy (apply the catalogue rule that matches the classification; see Rules), rescue (hand the PRs no rule recognised over for rescue; see Rescue handoff), mark (write markers and evidence comments). remedy needs mark and is refused without it: the one-attempt-per-change guard reads the evidence marker, so a remedy that writes none repeats on every sweep. rescue runs only when named, never by default; it needs remedy, since only the rule stage says no rule recognised a failure, and the team scope, since a rescue is counted against a team's week. --dry-run decides every outcome and writes nothing, labels included.
The rescue step hands the PRs no rule recognised to whoever runs the rescue: the agent the weekly run executes inside, or a person in their own Claude Code. It pushes nothing and writes no marker; the rescuer does the work and writes the outcome with marge mark. A PR is handed over when all of these hold:
- its failure is one no rule of the catalogue recognised, on a PR of a trusted bot;
- no security check failed, and no check is still running. A required check that never reported refuses the PR unless a required check failed: a job behind the failed one (a CircleCI job whose required job failed) runs only on the head the rescue pushes;
- the team's policy, and the repository's exception, allow rescues;
- no rescue marker stands for the change on the branch;
- the team's weekly count is not spent: every rescue marker of the last seven days on the team's PRs counts, merged and closed PRs included. The count stops at the weekly limit, and one that cannot be read, or would read the comments of more than 200 PRs before reaching it, hands nothing over;
- a read just before the handoff finds the PR still open, on the head the sweep classified, without a conflict;
- no open PR of a person changes a file the bot PR changes. A bot PR whose diff could not be read collides with every open PR of a person;
- with
--toolchain, the repository's language is the one the run's image builds. The language is the team file'sgen.language, unless the repository root carriesgo.mod,package.json,pyproject.tomlorrequirements.txtfor another one, which wins and is noted.
The candidates are taken one repository at a time. A PR handed over is labelled marge/rescued until the next sweep. --output json carries the handoff as rescue_handoff: team, triggered_by (the login, or --triggered-by), toolchain, budget (weekly, used (counted up to weekly), remaining, and the declared timeout and per_rescue_usd), repositories (each with its language, and its PRs with url, kind, update_type, head_sha, write_target, failing_checks with the log URL of each, signature and excerpt) and refused (each candidate turned away, with the reason). write_target is pr-branch, or default-branch for an Align files PR, whose branch is regenerated every cycle.
marge sweep --team bumblebee --actions remedy,rescue,mark --toolchain go --output jsonThe remedy step matches a classified PR against a catalogue of rules and applies the action the matching rule names. Rules live in this repository under rules/, one YAML document per file, and are read at the start of every sweep from the default branch. The binary does not embed them, so a merged rule is live on the next run without a release. --rules-ref, --rules-repo and --rules-path change where the catalogue is read from; --rules-path reads a directory on disk, which is how a rule is tried before it is merged.
A rule carries a detection signal, the name of one action, refusals it adds, and the evidence line written on the PR. The signal is a check-name glob (match.check.name), a bounded log-excerpt expression (match.log), PR metadata (match.pr) -- the title (titlePattern), the diff (files), or what the base head reported for the failing checks (baseHead) -- or the base branch's protection (match.protection.missingContexts), globs over the required contexts the head never reported. A baseHead condition must hold for every check the rule selected, so a PR carrying one transient failure and one real failure matches neither green nor red. A glob that matches everything is refused wherever one is accepted: a rule names at least one literal segment, or it is a classification restated rather than a signal.
match.check.name reads the checks that failed. match.check.state: pending reads the checks that have not finished instead, and it requires match.check.output.pattern, an expression over the title, summary and text the check itself reports. A gate check is why: it stays pending until the job it waits for reports, so it is neither a failing check nor a context nobody reported, and its message is the only thing it says about the head. The pattern needs a capture group named command, every match is kept, and an action reads the captures rather than composing a string of its own. A pending signal takes no match.log and no baseHead: a check that never ran has no log, and the rule selects no failing check for a base state to answer for.
match.log.source is optional. A rule that leaves it out reads the log of the failing check from the provider that ran it, so the same failure is recognised on GitHub Actions and on CircleCI without a second copy of the pattern. A rule whose pattern is evidence on one provider only names that provider and keeps reading it alone.
name: circleci-auto-cancel
summary: A build CircleCI itself cancelled established nothing about the code.
source: runbook row 74
match:
states: [failed]
check:
name: "ci/circleci: *"
log:
source: circleci
pattern: 'canceled'
action:
name: circleci-retry
evidence:
reason: the auto-cancelled build was retried on the same commitThe actions a rule may name are update-branch, rerun-failed, circleci-retry, close, mark-wait, comment-command, dispatch-cve-workflow and fix-protection-context. A new action is a Go change, reviewed as code. rerun-failed reads the matched check's URL and reruns the failed jobs of the Actions run or the CircleCI workflow behind it, so a rule that names a transient failure remedies it on either provider.
comment-command comments the command a pending gate check named, so the test suite the gate waits for starts. It writes no commit, so no approval is dismissed and no CI cycle restarts, and the PR stays in the state the sweep classified it in. The command is the one the rule captured from the check's own message: the action composes none, and the known-command guard accepts only a /run command with KEY=value arguments naming a suite the sweep knows. only-gate-waiting refuses while anything else on the PR is red or pending, because the suite costs a cluster and a PR whose other checks fail does not merge when the suite goes green. up-to-date refuses while the branch is behind its base, or when the comparison cannot be had, because a suite run on a stale branch tests code the merge does not ship. When it is the only refusal and the branch is behind, the sweep updates the branch through update-branch and its guards, and the command is commented on a later sweep once the branch is up to date.
The Tekton comment trigger (giantswarm/pr-comment-filter, deployed by giantswarm/tekton-resources) starts a suite only for a /run comment from an active giantswarm organization member or from a bot whose numeric user ID is in the trigger's ALLOWED_BOT_USER_IDS. giantswarm-marge[bot] (329428426) is on that list, so a scheduled sweep running as the App starts the suite just as a person running the CLI does. Any other App's comment is refused without a reply on the PR. The heimdall-suite-not-triggered rule refuses once-per-change, so a PR gets at most one command per head. A run also starts at most --suite-limit suites (2 by default, suiteLimit in the chart), counted per /run line across every team it sweeps, because every suite builds clusters on the shared test management cluster and its Flux helm-controller stalls when too many reconcile at once. A comment that does not fit is refused whole, writes no marker, and is commented by a later run.
Documents are decoded strictly, so an unknown key is an error. A rule whose only signal is a check name or a title is refused: a name says which job went red and a title says which dependency moved, neither says why, and titlePattern: "." reads every PR of a classification. Such a rule must carry a log signal, or read the PR's state rather than its text through baseHead, files or match.protection.missingContexts. A glob that matches everything is refused wherever one is accepted, so files: ["**"] is no way around it. A rule cannot do what its action forbids: each action enforces its own guards, a rule may only add refusals, and there is no syntax for removing one. The guard vocabulary is the trusted bot author, no failing security check, the required checks, checks settled on the head, one attempt per change, no rescue standing for the change, a log excerpt behind every write, the commands a comment may carry, the gate being the only wait left, the branch being up to date with its base, and the generated files a remedy may never hand-edit. Each action carries the subset it needs, not all of them, and marge rules validate prints the set an action enforces. Rules are tried most specific first, by how much each one asks of a PR, and by name among equals; the first match wins. A broad rule therefore never shadows a narrow one, and a catalogue decides the same way however it was read.
A failure no rule recognises is grouped by signature in the sweep's JSON output under unhandled, most frequent first, and written on the PR itself as an evidence marker carrying the signature, the failing checks and the log excerpt the rules already fetched. The run ends and its grouping ends with it; the marker is what persists, so the same failure on eleven PRs is eleven records that can be counted. The marker is written once per change and goes stale when the branch moves, like every other marker.
marge rules signatures counts those markers by signature over the last --days, the one on the most PRs first. marge rules draft <signature> writes a rule skeleton and a pair of scenarios built from the PRs that carry it, then opens a draft pull request carrying the same files; it reads the markers, so no saved report is needed, and --from <report> reads a saved sweep report instead. The skeleton leaves the action blank, so it does not validate until a person names one; promoting a pattern is editing a draft rather than authoring one. A scheduled sweep's summary names the top signatures of the run, which is a pointer to the markers rather than the only record of them.
The pull request is opened through the API -- a tree, a commit, a branch and the pull request -- so marge needs no git workspace, no push credential and no language toolchain, and an agent running the sweep opens it with the token the sweep already uses. That token needs contents: write and pull-requests: write on the repository; a read-only sweep token is not enough. The branch is rule/<name>, one per rule, so a second draft of the same pattern reports the pull request already standing rather than opening another. --repo and --base say where it lands, and --no-pr writes the files and stops, printing the git and gh commands instead.
marge rules validate decodes and validates every document; marge rules test replays the recorded scenarios under rules/testdata against the catalogue. A scenario whose subject records evidence (the markers earlier sweeps left: outcome, head, base, patchID, next to the subject's own head, base and patchID) or a rescue also asserts what the action's marker guards say, expect.refused being the reason, or empty when a new attempt may run. A subject's rescue (tool, outcome, reason, head, patchID) is the newest rescue attempt's marker, which no-fresh-rescue reads the same way. Both run in CI as ordinary Go tests, so a rule without one scenario that matches it and one that refuses it cannot merge. docs/patterns.md carries the failure patterns the engine does not act on and the hazards behind the guards. skills/marge is the skill a person loads in Claude Code to drive a sweep; its hazards reference condenses those hazards and the known-pattern hints for the model that runs when no rule matched. The repository is a Claude Code plugin (.claude-plugin/plugin.json), which the Giant Swarm marketplace pins by commit. The AgentTemplate that loads the skill as a commit-pinned git source is not in this repository yet.
A rule that fails to validate is skipped and named on stderr and in the JSON rules object; the rest of the catalogue still runs. A catalogue that cannot be read at all refuses every remedy for that run and leaves classification, approval and merging unchanged. Every sweep reports the catalogue digest it ran, and every evidence comment names the rule and that digest.
When a PR's CI fails, marge classifies the failure as security-related if any failing check's name contains one of the configured substrings (case-insensitive). Security failures are surfaced separately so they are not mistaken for ordinary build/test flakiness.
The built-in list contains: security, govulncheck, trivy, codeql, snyk, gosec, gitleaks, semgrep, checkov, kics, vulnerability, vulnerabilities, sast, dast, dependency-review, dependency review.
Pass --security-patterns "Analyze" to add to the list; it cannot be narrowed. The github/codeql-action template uses a job name like Analyze (<lang>) that the codeql substring will not match, so add Analyze if you rely on that template.
Sometimes a check reports failure not because the code is broken but because GitHub never started the job -- a personal account or organization has exhausted its Actions budget. GitHub surfaces this as a job that never reached the runner:
The job was not started because an Actions budget is preventing further use.
Verified against the live GitHub API, such a block shows up as a check run with conclusion failure, empty output, and a single failure-level annotation whose message carries the text above (the message is in the annotation, not the output fields). marge therefore inspects each failed check run's annotations and matches that message -- which never appears for a genuine test, build, or lint failure.
When every failing check on a PR is such a block, marge classifies the PR as CI unavailable (budget) rather than Failed. It is counted separately, surfaced under its own section, and kept out of any rescue path -- the fix is to raise or await the Actions budget, not to touch the code. If a PR has a mix of a genuine failure and a budget block, it is still reported as Failed.
Only this API-verified message is matched; any unrecognized block degrades to the normal
Failedpath rather than risking a real failure being hidden.
A check also reports failure when it established nothing about the code. Two shapes are recognised, and each carries its own remedy in the detail:
- The job was cancelled. The check run concluded
cancelled. This needs no message and costs no extra request: a job that was killed built, tested and scanned nothing. Rerun it. - CircleCI refuses the pipeline. A repository whose
.circleci/config.ymluses a setup workflow while the project setting that allows it is off getsUse of setup workflows must be enabled in project settings (Project settings > Advanced -> Dynamic config using setup workflows). CircleCI reports it in the commit status description and, for the CircleCI GitHub app, in the check run output. No branch fix and no rerun resolves it: somebody has to change the setting once per repository.
A timed_out conclusion is deliberately not in this bucket. GitHub sets it when a job exceeds its time limit, which usually means the job ran and hung, and a dependency bump that deadlocks a test produces exactly that shape. It stays on the Failed path where the regression is visible.
A check is judged by its newest run on the head. GitHub lists every workflow run's check runs on a commit, so a workflow started twice on one head (Renovate's opened and edited events arrive a second apart, and the workflow's concurrency group cancels the first run) lists its check twice: once cancelled, once with its verdict. Only the newest run counts, for the required-check guard as much as for this bucket, so the cancelled first run neither fails the PR nor reports it as CI unavailable (no verdict). A check whose newest run was cancelled is still a check without a verdict.
When every failing check on a PR is such a check, marge classifies the PR as CI unavailable (no verdict) rather than Failed, with a detail naming each check and why: CI unavailable (no verdict) (checks produced no verdict: publish / gitleaks (cancelled before it finished)). It is counted separately, surfaced under its own section, and kept out of any rescue path. A PR with a mix of a genuine failure and such a check is still reported as Failed, and the check without a verdict is left out of the failure list.
This matters most for a security check. Failed (security) is the one category an operator is trained never to wave through, so a gitleaks job that was cancelled before it scanned anything would draw manual attention and discourage the rerun that actually fixes it. A security check that established nothing is therefore never reported as a security failure; a scan that ran and found a secret still is.
Renovate leaves two open PRs for one dependency whenever a major lands while a minor is still open, and it opens a PR for a pinned action even when upstream moved only the tag. A failing or conflicted PR of either shape looks like work and is not. marge reports it as Obsolete and keeps it out of the action-required list. Two rules produce that verdict, and the report says which one fired:
- Superseded. Two or more open bot PRs in the same repository and on the same base branch whose titles name the same dependency: the one with the highest target version wins and every other one is reported as
Obsolete (superseded by #30 (v7.0.1)). The comparison is semver on the titles, and a PR is only superseded on positive evidence -- both titles must name a dependency and a target version, both versions must parse, and equal versions supersede nothing. It is decided from the sweep's PR list alone, so it costs no request. - No-op. A PR whose diff changes nothing that executes. The rule is narrow on purpose: every changed file must be a
.github/workflowsor.github/actionsYAML file, and every changed line must be auses:line pinned to a full commit SHA whose pin is unchanged and whose trailing version comment is all that moved. Anything else -- a moved SHA, a tag ref, a re-indented line, a file elsewhere, a patch GitHub truncated -- keeps the PR as it was. The diff is fetched only on the paths that would otherwise report work, and only when the supersession rule did not already fire.
- - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
+ - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
Neither rule suppresses a merge: a green PR still merges, whatever its siblings carry. The sibling can be a major that CI rejects, and the safe lower bump must still land. The verdict only replaces a failure or a conflict, where the remedy is to close the PR rather than to rescue it.
marge never closes a PR itself. Two PRs can legitimately carry the same dependency name in one repository, for instance across the manifests of a monorepo, so the decision stays with a human. PRs found through a GitHub issue search carry no base branch, because the search API does not report one; those group as if they shared a branch. Sweeps driven by --repos-file or repos know the base branch and group by it.
Two bot PRs of one repository often edit the same file. The PRs of a repository are processed one at a time, so the first merge makes the second one dirty. The conflict is real, but it is not work for anybody: the bot rebases its own PR within about a minute, and the PR is mergeable again.
marge reports such a PR as Awaiting rebase (label marge/pending), never as a conflict, and names the sibling that caused it: conflicted by #6, merged in this run; the bot rebases it. No rule of the catalogue acts on that state, so no rescue is started.
The sweep then looks at the PR again in a second pass, after the rest of the run. It waits for the bot to rebase, up to three minutes for the whole pass, and processes each rebased PR as usual: green and eligible, it merges in the same run. Without that pass the PR would wait for the next sweep, which is a day later, and each further PR of the repository would wait behind it. A PR the bot has not rebased when the wait runs out keeps Awaiting rebase and the next sweep decides.
Renovate rebases only a branch it still considers its own. A Renovate PR whose last commit is by anyone but Renovate or marge is therefore reported as Conflict, whoever caused it, with the step that hands the branch back: merge conflict; the last commit is by <login>, so Renovate does not rebase the branch: tick the rebase checkbox in the PR body.
A conflict on a PR of a repository this run did not merge into is unchanged: it is reported as Conflict and counted as action-required. A PR with GitHub auto-merge enabled needs none of this, because GitHub merges it when the rebase lands.
A dependency PR is built once and then sits in the queue while the base branch moves on. When a fleet-wide fix lands on main -- a CVE bump that turned every open Go PR's vulnerability scan red, a linter pin, a CI infra repair -- the PR's last build stays red although the failure no longer exists. Without help, an operator (or a rescue agent) spends time diagnosing a failure that a branch refresh would have cleared.
marge recognises this case. When a PR's checks fail, it:
- compares the PR head with its base branch (
GET /repos/{owner}/{repo}/compare/{base}...{head}) and continues only if the head is behind (behind_by > 0); - looks up the latest run of every failing check on the base branch head (commit statuses and check runs);
- classifies the PR as
Staleinstead ofFailedwhen all of them are green there, e.g.Stale (go-build green on main since 2026-09-05 10:57 UTC, 12 behind).
A PR that is behind but whose failing check is also red on the base branch stays Failed -- the failure is real on main too. So does a PR whose failing check does not exist on the base branch at all (a PR-only workflow cannot be proven green), and a PR that is not behind. Any lookup error keeps the Failed classification; a stale verdict is only ever reached on positive evidence. The check runs before the security split, so a stale govulncheck or Trivy failure is recognised like any other.
Stale PRs are listed in their own Stale section, counted separately from failures, and kept out of the action-required list -- the remedy is a refresh, not a rescue. With the refresh action (selected by default; --actions narrows it) marge performs that refresh itself: it calls PUT /repos/{owner}/{repo}/pulls/{number}/update-branch (the same merge commit as GitHub's "Update branch" button) and reports the PR as Refreshed (re-checking; ...). CI re-runs against current code and the next sweep merges the PR if it is green -- or reports it as Failed, because it is no longer behind.
Three guards apply to the refresh:
--dry-runprints theStaleclassification and what a real run would do (dry-run: update-branch would apply, or the refusal it would meet) but never calls update-branch.- One refresh per change and base head. The evidence marker of a refresh records the base head it merged (
base_sha). The same change is never refreshed twice from the same base head, but once the base moved on, a PR that is stale again is refreshed again. A marker written before the base was recorded blocks only until its refresh has landed on the head. - A PR carrying a non-stale rescue marker is not refreshed, by the sweep's own refresh or by a rule that names
update-branch: the action'sno-fresh-rescueguard refuses and names the marker (Stale (...; update-branch refused: fresh rescue marker: rescue blocked 2d ago (klaus), rebased since: same change)), the marker itself with its reason shown beside the entry. The marker pins the change an automated rescue already failed on -- whether the branch was rebased since or not -- so re-running CI against a newer base cannot help. The marker is shown on the entry so the operator can decide. A stale marker (the PR content changed since the attempt) does not block the refresh.
The heuristic is deliberately cheap: main being green does not prove the bump itself is innocent (a major bump can be red for its own reasons while main is fine). The cost of a wrong Stale verdict is one branch refresh and one CI run, after which the PR is no longer behind and is classified on its own merits.
CircleCI cancels a running build on its own when a newer pipeline starts on the same branch (Renovate pushed a rebase or a new version while the previous build ran) or when it detects a redundant workflow. The cancelled build still posts failure -- "Your tests failed on CircleCI" -- to the commit it was building, and the status description carries no hint of the cancellation. Read at face value, the PR looks like a real failure and costs an operator (or a rescue agent) a diagnosis that ends in "nothing is wrong, just retry".
marge looks behind the status. When every failing check of a PR is a commit status whose target_url points at a CircleCI build (https://circleci.com/gh/<owner>/<repo>/<build>), it fetches that build from the v1.1 API (GET /api/v1.1/project/github/<owner>/<repo>/<build>) and inspects its steps. Verified against the live API: an auto-cancelled build reports status: failed and canceled: false at the top level, exactly like a real failure -- but its steps are all success up to the cancellation and only canceled from there on, whereas a real failure has a step with status: failed. A build cancelled before any step ran reports status: canceled instead. Both shapes classify the PR as Cancelled rather than Failed:
- On the current head --
Cancelled (build 1263 auto-cancelled; retry needed): the commit has no verdict yet. With theretryaction (selected by default;--actionsnarrows it) marge callsPOST /api/v2/workflow/<workflow_id>/rerunwith{"from_failed": true}on the workflow the build belongs to (itsworkflows.workflow_id, part of the v1.1 build JSON), and reports the PR asRetried (re-checking; workflow build rerun from failed). The next sweep reads the real result. The workflow rerun also releases the jobs the cancel leftblockedornot_run; the v1.1 single-build retry does not, so on a repository whose branch protection requires those downstream contexts the PR would go green on the retried job and stay unmergeable. Each distinct workflow is rerun once, however many of its jobs were cancelled. CircleCI reruns from a failed job, so two cases have none -- a build outside a workflow, and a workflow cancelled before any job failed, which the endpoint turns down with400-- and both fall back toPOST /api/v1.1/project/github/<owner>/<repo>/<build>/retry, reported asRetried (re-checking; build 1263 retried as 1272). A rerun refused for any other reason, an expired token for instance, leaves the PRCancelledwith the error: the retry would meet the same wall. - Behind a newer head --
Cancelled (build 1244 (2c0ce64) auto-cancelled; head is now 605a2d6, its build is the verdict): the branch moved on and the new head's own build decides. Nothing is retried.
Cancelled PRs are listed in their own Cancelled section (and Retried once retried), counted separately from failures and kept out of the action-required list. The lookup is lazy -- nothing is fetched unless a failing status points at CircleCI -- and it is decided before the stale and security classifications because it rests on positive evidence about the very build that failed. A PR with a mix of a cancelled build and a genuine failure (a failing GitHub Actions check run, a CircleCI build with a failed step) stays Failed. --dry-run classifies but never retries.
Public CircleCI projects can be inspected without credentials. Private projects and every rerun endpoint need a CircleCI API token (see Setup). Without one, a private project's build cannot be inspected and the PR keeps today's Failed classification, annotated: Failed (checks failed: ci/circleci: go-build; ci/circleci: go-build: build 1263 could not be inspected (HTTP 404: Build not found; no CircleCI token configured (private project?))). A cancelled build on the current head with the retry action but no token is reported as Cancelled (...; retry skipped: no CircleCI token configured).
CircleCI can run every job of a pipeline to success and post none of their ci/circleci: <job> statuses to GitHub. The PR would then wait for ever on required checks that will never report. When a waiting PR's head has settled for ten minutes, nothing is pending, and a missing required context is a CircleCI one, marge reads the head's pipelines from the v2 API (GET /api/v2/project/gh/<owner>/<repo>/pipeline?branch=<head branch>, pull/<n> for a fork) and the workflows and jobs of the newest pipeline for the head revision:
- The pipeline finished and its jobs carry the missing names -- with the
retryaction marge reruns each such workflow from the beginning (POST /api/v2/workflow/<id>/rerunwith{"from_failed": false}) and reportsRetried (re-checking; workflow build (pipeline 483) rerun (statuses not posted)). A rerun happens once per head: CircleCI records it as a workflow run taggedrerun-…in the same pipeline, and a head whose workflow was rerun and still posted nothing is reportedCI unavailable (no verdict) (...; workflow build (pipeline 483) rerun once on this head, statuses not posted again). A new head has its own pipeline and gets its own rerun. Without theretryaction, in a dry run or without a token, the PR is reportedCI unavailable (no verdict)withrerun neededor the reason the rerun was skipped. - CircleCI has no pipeline for the head --
CI unavailable (no verdict) (...; CircleCI has no pipeline for head de4e48e, push a commit to start one). - A workflow still runs, or no job carries the missing names -- the PR keeps waiting; a context no job posts is a repository setting.
Every table and report includes an Age column showing how long the PR has been open (5h, 3d, 2w). PRs older than 3 days are highlighted yellow, older than 7 days red -- an old dependency PR has already survived several sweeps and is the most likely to need manual work. Failure sections are sorted oldest-first for the same reason.
When an automated rescue (a coding agent, a CI bot, a human with a script) tries to fix a failing dependency PR and gives up, it can record that attempt as a machine-readable ai-rescue marker inside an ordinary PR comment:
**AI rescue failed** (klaus), cost not reported: nock v14 is ESM-only and breaks Jest CJS resolution.
<!-- ai-rescue: {"tool":"klaus","outcome":"failed","reason":"ESM-only breaks Jest CJS","head_sha":"d9f00bf2","at":"2026-06-09T18:40:00Z","patch_id":"5ad45e13d66acc2b","change_id":"nock@v14"} -->On every sweep, marge reads the comments of each failing PR and annotates its entry with the most recent marker, e.g. [rescue failed 1d ago (klaus): ESM-only breaks Jest CJS]. The marker records what it was attempted against, and the sweep decides from that whether the attempt still describes the current PR:
head_sha-- the PR head at the time. Same head: the marker is fresh.patch_id(optional) -- a fingerprint of the PR's diff. When the head moved, marge recomputes it for the current head fromGET /repos/{owner}/{repo}/compare/{base}...{head}. Same fingerprint: the branch was only rebased (Renovate does this whenever the base moves) and the marker stays fresh, annotated[rescue blocked 5d ago (klaus), rebased since: same change: ...]. Different fingerprint (a new version, a pushed fix): the marker is stale ([rescue failed 3d ago (klaus), stale: new commits since]) and the PR is fair game for another rescue.change_id(optional) -- the cheap fallback for dependency PRs:<dependency>@<target version>parsed from the PR title (typescript@v7). It decides only when nopatch_idcan be compared, e.g. when the diff is too large for the compare API. A rebase never changes it and a new version always does, but a version update that keeps the title (7.0.1 -> 7.0.2 under "to v7") is invisible to it, which is why the diff fingerprint is preferred whenever it is available.
Markers without a fingerprint (written before it existed) age out with the head SHA alone, as before.
The patch_id is the first 16 hex characters of a SHA-256 over the compare response's files, sorted by path: per file its status, previous path and path, then every +/- line of the patch in order -- hunk headers and context lines are skipped, since both shift when the base changes around the PR's lines. A file without a patch (binary, pure rename) contributes its blob SHA. The fingerprint is left out when GitHub truncates the response (more than 300 files, or a file whose diff is too large to include a patch), so a partial diff is never mistaken for the whole change.
This makes the daily triage call obvious at a glance:
- failing + fresh failed rescue (rebased since or not) -> automation already lost; a human is needed
- failing + stale or no marker -> hand it over for (another) rescue
Use marge mark to write markers without knowing the format. Any tool that can comment on a PR can participate -- there is no coupling to a specific agent framework.
Sweeps one scope without interactive grouping. Exactly one scope is given:
--team <name>reads the team's repositories fromrepositories/team-<name>.yamlin the team-file repository (giantswarm/githubunlessMARGE_TEAM_FILE_REPOnames anotherowner/repo; each entry'snameis read, and itsbotPRsSweepkey when it has one; an entry whoselifecycleisarchivedordeletedis the record of a repository that takes no write and is left out) and sweeps their open bot PRs under the team's policy. It takes several names, repeated or comma-separated: each team is swept under its own repositories and its own policy,--parallelteams at once, and the teams are reported in the order named. Teams that own a common repository are swept one after another, so two sweeps never write to one PR at the same time. One team's unreadable policy fails that team alone; every other team still runs, and the command exits non-zero at the end. Naming several teams refuses--prs, which narrows a single scope.--query <text>runs marge's GitHub search the waymarge [query]does, for personal repositories and organisations without a team file;--organd--repos-filebelong to this scope. The query scope has no team, so the company defaults apply on their own.
A sweep does not wait for pending checks: a Waiting for checks PR is reported and the next sweep decides. --check-timeout opts into a wait.
A sweep runs its independent reads at once: the teams of a several-team run, the searches of the query scope and the documents of the rule catalogue, --parallel of each at once (8 by default; --parallel 1 runs them one after another). The PRs of one team are read 15 repositories and 4 PRs per repository at once, or the policy's wider bounds, and merged under the policy's bounds. Each token keeps at most 64 GitHub requests in flight, below the 100 concurrent requests GitHub allows before its secondary rate limit refuses them, and a refusal for rate holds every request of that token until the time GitHub names. The output is the same whatever order the reads answered in.
The live table shows every PR's outcome, including the failure reason and any ai-rescue marker, followed by a one-line summary. With --no-tui the results are printed as plain-text groups: Merged, Security failures, Failed, Stale and Refreshed, Cancelled and Retried, Obsolete (bot PRs a higher-version sibling replaces, and bot PRs whose diff changes nothing that executes, see Obsolete bot PRs), Waiting for checks, CI unavailable (Actions budget), CI unavailable (no verdict) (PRs whose failing checks established nothing about the code, see CI unavailable (no verdict)), and Skipped. With --output json the same structure the MCP sweep tool returns is printed, including repositories_failed for repositories whose PRs could not be listed and findings for the repository settings that hold a queue.
| Flag | Short | Default | Description |
|---|---|---|---|
--team |
Team whose repositories are swept (team scope); repeatable, or comma-separated, for several teams | ||
--post-summary |
false |
Post each swept team's summary to the Slack channel its policy names; a scheduled run sets it | |
--query |
GitHub search text (query scope) | ||
--actions |
(all but rescue) |
Comma-separated sweep steps to run, in fixed order: classify, changelog, approve, merge, refresh, retry, remedy, rescue, mark (see Actions) |
|
--triggered-by |
(login) | Who started the run, as the rescue handoff and the rescuer's markers name it | |
--toolchain |
Hand over for rescue only the PRs of repositories in this language, the one the agent's image builds | ||
--dry-run |
false |
Decide every outcome, write nothing | |
--check-timeout |
0 |
How long to wait for one PR's pending checks; zero reports the PR as waiting | |
--parallel |
8 |
How many teams, searches and rule documents the sweep reads at once; 1 runs them one after another. Teams that own a common repository are always swept one after another |
|
--rules-repo |
giantswarm/marge |
Repository the rule catalogue is read from, as owner/name |
|
--rules-ref |
main |
Branch the rule catalogue is read from | |
--rules-path |
Read the catalogue from this directory instead of the repository | ||
--watch |
-w |
false |
Keep polling for new PRs every 60 seconds |
--org |
Limit to repos owned by this org or user (query scope) | ||
--repos-file |
File with org/repo entries (one per line; blank lines and # comments are ignored) to scan instead of searching GitHub (query scope) |
||
--prs |
Sweep only these pull requests of the scope, each a PR URL or owner/repo#number (repeatable, or comma-separated). It is a scope of its own: given alone, the repositories of the listed PRs are read. A listed bot PR of the scope that has merged or closed is reported as merged since the list was read (Already merged) or closed since the list was read (Skipped) and the run goes on; any other PR the scope does not find refuses the run |
||
--no-tui |
false |
Disable the live table; print plain-text results instead | |
--output |
table |
table or json |
|
--merge-auto |
false |
Also merge PRs that have auto-merge enabled (by default the merge itself is left to GitHub) | |
--suite-limit |
2 |
How many e2e suites the run may start through comment-command, across every team it sweeps; 0 starts none |
|
--security-patterns |
(built-in) | Add to the built-in security check pattern list (see Security check patterns) |
Records the outcome of an AI rescue attempt on a PR by posting an ai-rescue marker comment, with what the attempt cost and who started its run. Every marker counts against the team's weekly rescue number. The marker captures the PR's current head SHA plus a fingerprint of its diff (patch_id) and, for dependency PRs, of its title (change_id), so it goes stale when the PR content changes but survives a Renovate rebase that leaves the diff unchanged. The confirmation line lists what was pinned, e.g. Marked my-org/my-repo#42: rescue blocked (head 1be1ed9d, patch_id 5ad45e13d66acc2b, change_id typescript@v7).
| Flag | Default | Description |
|---|---|---|
--outcome |
failed |
Rescue outcome: fixed (a fix is pushed and CI runs again), merged, failed (attempted, could not fix) or blocked (fix known but waits on something external) |
--reason |
Short explanation of the outcome | |
--tool |
ai |
Name of the tool/agent that attempted the rescue (e.g. klaus) |
--cost-usd |
Estimated cost of the attempt in US dollars, as the agent reported it; unset, the marker says cost not reported |
|
--duration |
How long the attempt took | |
--dispatched-by |
Who started the run: the handoff's triggered_by |
|
--run-id |
The run the attempt belongs to | |
--dry-run |
false |
Show the marker that would be written, head SHA and fingerprint included, and post nothing |
marge mark https://github.com/my-org/my-repo/pull/42 \
--tool klaus --reason "nock v14 is ESM-only, needs Jest ESM migration"Requires the token to have Issues: Read & write (comment) permission in addition to the permissions listed under Setup.
Starts an MCP server exposing six tools: list, sweep, remedy, rescue, mark and changelog. Each one is an adapter over the same engine call the CLI makes, with the same guards, so a tool call and the equivalent marge sweep invocation do the same thing. Every tool that can change a PR takes dry_run and carries the MCP read-only and destructive annotations, so a client knows what a call costs before making it. docs/tools.md lists every tool's description and input schema as a model reads them (make tools-doc regenerates it).
-
list-- read-only. The open bot PRs of a scope with the classification of each. The result has the same shape assweep's, so "what is waiting for us" and "what would a sweep do" are one question.refreshchooses where the classification comes from, and the two readings cost very different amounts:refresh: false(the default) reads back the classification the last sweep stored in the PR'smarge/<class>label, which the PR search already carries. The whole call costs the search, whatever the number of PRs. Several states share one label, so thestatusis the class's representative --pendingcovers a wait, a cancelled build and a retry,stalecovers a refresh -- and each of those states asks the reader for the same next step; the evidence,update_type,policyandrescueeach need the PR itself and are left out. A PR no sweep has labelled is reported underunclassifiedrather than guessed at.refresh: trueclassifies every PR again: theclassifystep alone on a dry run, with the evidence, the update type, the resolved policy and the prior-rescue state of each. Nothing is approved, merged, refreshed, retried, remedied or labelled. It costs a check read per PR.
teamscovers several teams in one call, each read under its own team file and policy. The answer is then{"teams": [{"team": ..., "result": ...}]}, one entry per team in the order given, and a team whose files are missing or unreadable carries anerrorinstead of aresult. The teams share one discovery, so reading every team costs one listing rather than one per team. It is refused together withteam,query,org,reposandrepos_file. -
sweep-- mirrorsmarge sweep, returning structured JSON (marge_version,rules,unhandled,summary,merged,security_failures,action_required,stale,refreshed,cancelled,retried,obsolete,waiting,ci_unavailable,ci_no_verdict,skipped,eligible,unclassified,not_reached,rate_limit,repositories_failed,findings, andrescue_handoffwhenactionsnamesrescue). Eachobsoleteentry carries areasonofsupersededorno_op. Eachfindingsentry carries acause, the count of the PRs it holds and the repositories it holds them in.teamselects the team scope;query,org,repos(a list oforg/repoentries) andrepos_file(a file in the--repos-fileformat) belong to the query scope and are refused together withteam.actionsselects the sweep steps like--actions,changelogamong them, andprsnarrows the run to the listed PRs (each a PR URL orowner/repo#number) like--prs; the scope still decides which repositories are read and under which policy, so a PR outside it is refused rather than swept. A listed bot PR that merged or closed after the caller read its list is reported inmergedorskippedwith that reason instead of refusing the run.teamssweeps several teams in one call, each under its own team file and policy, and answers in the same{"teams": [...]}shapelistdoes; the teams are swept together, except teams that own a common repository, which are swept one after another so they never write to it at the same time, and withprseach named PR is swept under the team that owns its repository. Each PR entry includespolicy(the resolved policy the PR was decided under, with thesourcesthat produced it),kind,update_type,label(the label on the PR after the sweep; absent when nothing was written, as indry_run),created_at,age_days,dependency,version_fromandversion_to(the title read as an update: what moves, and between which versions; a title that names no source version leavesversion_fromempty, and a title in no known shape leaves all three out), and -- when a prior rescue attempt was found -- arescueobject (tool,outcome,reason,at,stale,rebased).rebased: truemeans the PR head moved since the attempt but the diff did not (a Renovate rebase); such a marker is still valid andstaleisfalse. Agent orchestrators should take the PRs to rescue fromrescue_handoff, which applies these conditions and the team's weekly count. -
remedy-- classifies one PR and applies the catalogue rule that matches it, through the action that rule names and that action's own guards. It isclassify,remedy,markon a single PR, so the refusals and the evidence comment are the sweep's.rulenarrows the catalogue to one rule, which must still match the PR: naming a rule removes the others from the contest, it never forces an action onto a PR.teamdecides the PR under that team's policy. -
changelog-- writes one changelog entry on each PR named inprs, in the format theteam's policy declares, and commits it to the PR's own branch. It is the sweep'schangelogstep asked for by name, on the PRs a person picked, whatever the team's policy says about the sweep.dry_runreturns the line each PR would receive and writes nothing. Each entry of the answer carries theline, thepath, whether it waswrittenand thecommitit made, or the reason it wasrefused: a PR whose author is not a trusted bot, whose branch lives in a fork, that is not open, whose repository has no such file or generates its release notes from its commits, or that already carries the line. Asking twice writes once. -
rescue-- the sweep's rescue handoff on one PR:classify,remedy,rescue,markunder theteam's policy, which is required. A rule that matches still wins; a PR no rule recognised comes back inrescue_handoff, or in itsrefusedlist with the reason.triggered_byis the caller. -
mark-- mirrorsmarge mark, so rescuers record their own attempts:outcome,reason,tool,cost_usd(left out, the cost is not reported),duration_s,dispatched_byandrun_id. The result echoes what was pinned:head_shapluspatch_idandchange_idwhen they could be computed.
| Flag | Default | Description |
|---|---|---|
--transport |
stdio |
stdio (JSON-RPC over stdin/stdout, for an MCP client that starts marge itself) or streamable-http (the MCP Streamable HTTP transport, what the Helm chart runs) |
--http-addr |
:8080 |
Listen address for streamable-http |
Over streamable-http the MCP endpoint is /mcp; /healthz and /readyz answer the Kubernetes probes. The server stops on SIGTERM/SIGINT after draining in-flight requests for up to ten seconds.
list, sweep and remedy report progress to a call that carries a progressToken: a notifications/progress when the call starts, after every PR, when the run starts waiting on the PRs its merges made dirty, and every 15 seconds while nothing else changes. The progress value counts notifications, so it always increases; the message carries the PR counts (34 of 79 PRs done). A gateway that resets its timeout on progress therefore keeps a long sweep alive for as long as it is working. Over streamable-http a call that reports progress answers as an SSE stream.
A server that finds its executable replaced on disk (marge self-update renames the new binary over the path it started from) stops serving stale code: a call made after the replacement is refused with a message naming the restart, a call in flight is finished, and the server exits a second later so the host that started it starts the new binary. Every sweep result names the producing version as marge_version, and marge self-update prints the pid of a marge serve still running the replaced binary.
The two transports act as different people, because they serve a different number of them. A stdio server is started by the person using it and serves that one person, so it acts with their own credential: the App when the environment carries one, otherwise GITHUB_TOKEN, GH_TOKEN or gh auth token. A streamable-http server serves everyone who reaches it, so only a per-request credential can be right: it acts with the token the caller presented as a Bearer, which is what muster attaches from the person's GitHub grant. A call that carries no token is answered with a sign-in error and never with a credential the process happens to hold -- a shared server that fell back would attribute one person's merges to whoever configured it.
marge serve # stdio, for a local MCP client
marge serve --transport streamable-http --http-addr :8080marge version # Print the current version
marge self-update # Update to the latest releaseProcess all bot PRs interactively, grouped by repository:
margeFilter PRs matching a query and keep watching:
marge "my-org/my-repo" --watchDry run to preview what would happen:
marge --dry-runGroup by dependency instead of repository:
marge --grouping dependencyPreview a team's sweep, then apply it:
marge sweep --team bumblebee --dry-run
marge sweep --team bumblebeeSweep a handful of teams in one run and read one report:
marge sweep --team bumblebee,atlas --team phoenixRelabel a team's queue without approving or merging anything:
marge sweep --team bumblebee --actions classifySweep a personal organisation, including PRs with auto-merge enabled:
marge sweep --query "" --org my-org --merge-autoPrint the sweep result as JSON:
marge sweep --team bumblebee --output json- Resolves the scope and the policy: with
--team, the repositories of the team file in the team-file repository, the company default file and the team's own; otherwise the GitHub search for open PRs of the trusted kinds that request your review or live in your repositories, or the repositories of--repos-file, under the company defaults. A scope that names repositories lists their open PRs over GraphQL, twenty-five repositories a request. A repository whose PRs cannot be listed is reported, never silently dropped. - In interactive mode, groups results by repository (or dependency) and presents a selector.
- For each PR, in parallel (15 repositories at a time and four PRs per repository; the writes keep the policy's
concurrency, by default five in flight and one merge per repository):- Reads the PR, its kind and update size, its checks, the base branch's required status checks and its markers.
- Applies the guards in order: repository swept at all, trusted author, auto-merge, security check, required checks, red non-required checks, eligibility.
- Approves the PR if not already approved, then squash-merges it; a PR behind its base is brought up to date instead.
- On a failure, looks behind failing CircleCI statuses (auto-cancelled builds are
Cancelledand retried by theretryaction) and compares the failing checks with the base head (fixed there already isStaleand refreshed by therefreshaction). - Writes the classification label and, where it acted, an evidence comment.
- Displays a live-updating table with columns for repository, dependency, version, age, author, and status, fitted to the terminal's width: the widest column narrows first, and a value too long for it (a PR title that names no dependency) ends in
.... Failing entries are annotated with any prior AI rescue attempt found on the PR. Use--no-tuifor plain-text output or--output jsonfor the structured result.
make build # Build the binary
make test # Run tests
make lint # Run golangci-lint
make help # Show all available targetsMIT -- see LICENSE for details.