Polls a single GitHub repo and shepherds one PR at a time toward merge: it picks the highest-priority eligible PR, rebases it onto the base branch, tracks it, and keeps it rebased every time the base branch moves until it merges. Then it moves on to the next one.
Rules, re-evaluated on every poll tick:
-
Eligibility. Only approved, non-draft PRs are considered; everything else is skipped entirely. PRs with failing CI are excluded until a new commit is pushed.
-
Priority (default; oldest-first within a tier):
- auto-merge on and CI passing
- CI passing
- auto-merge on
PRs matching none of these are not rebased. "CI passing" means all checks named in
ciCheckssucceeded (or, ifciChecksis not set, the overallstatusCheckRollupis green). -
Preemption. If a PR reaches a strictly higher tier than the tracked PR, the bot switches to it immediately and rebases it. The CI re-run that the bot's own rebase triggers does not demote the tracked PR.
-
Stale timeout. If the tracked PR hasn't merged within
STALE_TIMEOUT, it is marked stale and the bot moves to the next PR. A stale PR becomes eligible again once the author pushes a new commit. -
Conflicts. A PR that conflicts gets a comment, is marked conflicted, and the bot moves to the next PR in the same tick. It becomes eligible again once the author pushes a new commit.
-
A tracked PR that merges, closes, loses approval, becomes a draft or starts failing CI is dropped and the next PR is picked.
See docs/superpowers/specs/2026-09-15-auto-rebase-bot-design.md for the full
design.
-
Create a GitHub App on the target repo with permissions:
Pull requests: Read & write,Contents: Read & write,Commit statuses: Read,Checks: Read(needed to read GitHub Actions check-run results viastatusCheckRollup—Commit statusesalone only covers the older classic Status API and won't see Actions check runs). If branch protection requires status checks to re-run, no extra permission is needed — pushes trigger CI normally. If you change an existing App's permissions, an org owner must approve the update on the installation (Settings → installed GitHub Apps → review request) — updating the App definition alone does not apply to an already-installed instance. -
Install the app on the repo and note the installation ID.
-
Set environment variables:
Variable Required Default GITHUB_APP_IDyes — GITHUB_APP_PRIVATE_KEYyes — GITHUB_APP_INSTALLATION_IDyes — GITHUB_REPOyes — ( owner/repo)BASE_BRANCHno mainPOLL_INTERVAL_MSno 60000GIT_WORKDIRno .git-workdirDB_PATHno ./pr-queue.dbSTALE_TIMEOUTno disabled (never stale) CONFIGno built-in defaults CONFIG_PATHno built-in defaults STALE_TIMEOUTis how long a tracked PR may stay open before the bot gives up on it and moves on, e.g.30s,5m,16h,40d, or combined like1h30m(units:ms,s,m,h,d).CONFIGholds a JSON config inline (takes precedence);CONFIG_PATHpoints to a JSON file instead. Unknown keys are rejected. Keys:{ "ciChecks": ["build", "test"], "priorityOrder": [["AUTO_MERGE_ON", "CI_PASSING"], ["CI_PASSING"], ["AUTO_MERGE_ON"]] }ciChecks: names of the required CI checks (GitHub Actions job/check-run names or classic commit-status contexts). CI counts as passing only when all of them succeeded, failing if any failed, and pending while any is missing or still running. Other checks are ignored. If omitted, the overallstatusCheckRollupstate is used.priorityOrder: each inner list is a tier whose rules must all match; earlier tiers win, and oldest-first breaks ties within a tier. PRs matching no tier are never rebased (an empty tier[]matches everything). Rules:AUTO_MERGE_ON,PR_APPROVED,CI_PASSING,CI_PENDING. Unapproved, draft, and failing-CI PRs are always excluded before ranking. The default is shown above.
-
npm install && npm run build && npm start
cp .env.example .envand fill in the required variables (the private key must keep its real line breaks — see the comment in.env.example).docker compose up --build
State (GIT_WORKDIR, DB_PATH) is persisted in the auto-rebase-data
named volume, mounted at /data.
npm test— unit + local-git integration tests (no network required).- Manual end-to-end verification against a real repo/App installation is a separate manual runbook, not part of automated CI (see spec's Testing Strategy section).