​

Auto-Merge

​

Enabling

# inspect current state
curl http://localhost:3011/api/merge-train/config

# turn auto-merge on (a POST needs the dashboard's internal token)
curl -X POST http://localhost:3011/api/merge-train/config \
  -H 'content-type: application/json' \
  -H "x-overdeck-internal-token: $(cat ~/.overdeck/internal-token)" \
  -d '{"require_uat_before_merge": false}'

# turn it back off
curl -X POST http://localhost:3011/api/merge-train/config \
  -H 'content-type: application/json' \
  -H "x-overdeck-internal-token: $(cat ~/.overdeck/internal-token)" \
  -d '{"require_uat_before_merge": true}'

1. the issue is open in the tracker (the cached tracker row) and opted in to auto-merge: its auto-merge / hold-for-uat label, then the project default, then this toggle (no forge read);
2. the merge gate (evaluateIssueMergeGate) says the PR is ready. Approval is a trusted overdeck-verdict marker comment whose sha= is the PR head, or a trusted reviewer’s standing GitHub review approving that exact commit, so a repo without branch protection still qualifies. “Trusted” is the marker rule: OWNER, MEMBER or COLLABORATOR, or the identity Overdeck posts as. The App’s bot is the installed App’s own (<slug>[bot], from the app-slug file beside its credentials in ~/.overdeck/github-app/, else GET /app), matched as a GitHub Bot account, never by login alone. Its reviews arrive as CONTRIBUTOR and count through that match. With the GitHub App configured, an approving marker counts only from the App’s bot: agents hold the operator’s gh credentials and could post one as the owner. If the App’s slug cannot be read, no bot approval counts. A review from any other account never counts, and each reviewer’s latest review stands: a later “Request changes” or a dismissal withdraws an approval. An approval of an older commit, or a marker without sha=, never counts. A GitLab MR needs a named approver in approved_by (what glab mr approve records); a green, conflict-free MR nobody approved is not approved, even where the project requires zero approvals;
3. the issue’s latest auto-merge entry allows a new one.

• the final gate check reads the feature/<id> PR fresh (no facts cache), and the merge refuses when the PR it would land is not that PR;
• a clean PR merges directly only when its live head is the approved head, pinned to it (gh pr merge --match-head-commit, the App merge’s sha, glab mr merge --sha);
• a PR that needs a rebase is rebased by the server only, and only when the worktree and origin/feature/<id> are both at the approved head. The server rebases exactly that commit in its own detached worktree, created at the approved head under a temporary path the work agent never uses and removed afterwards, so nothing the agent commits in its worktree meanwhile can become the rebased head. It moves the work agent’s worktree to the result for local verification (only while that worktree is still at the approved head), pushes the result by sha with a lease on the approved head, and pins the merge to it. It never hands the rebase to the work agent, whose push would merge unreviewed. The pushed head is new, so if verification or the merge then fails, the PR needs a fresh review before it can merge automatically again;
• polyrepo merge sets and branches that track .planning/ files are left to the operator: an automatic merge refuses them;
• a git read that fails while checking where the merge may start (a fetch or rev-parse failure) is retried within the merge retry budget instead of failing that head for good. A head that was read and differs fails it.

​

Per-project default

​

Per-issue override

• auto-merge: this issue auto-merges when eligible, whatever the project or global setting says.
• hold-for-uat: this issue waits for a human batch review, whatever the project or global setting says.

​

Eligibility

• The PR is open (not closed, not a draft, not already merged)
• The PR is approved on its exact head commit (a trusted reviewer’s standing GitHub review of that commit, or a trusted verdict marker whose sha= names it, posted by the GitHub App’s bot when the App is configured; on GitLab, a named approver in approved_by), and no review or marker requests changes
• The forge reports CI checks on the PR head, and all of them passed. Pending checks, failing checks, and no reported checks each make the PR ineligible. When the project runs verification.tests: ci, the CI test job must also have run and passed on that head.
• The forge reports the PR as mergeable (no merge conflicts, branch protection satisfied). A PR whose mergeability the forge has not computed yet is not eligible.
• The issue is not held for UAT (its label, then the project default, then the global setting; see above)
• None of the blocker labels are present on the issue:
  • needs-design
  • needs-discussion
  • do-not-merge

​

Cooldown

​

Cancelling

1. The Pending auto-merges card on the dashboard’s Flywheel page has a Cancel button.
2. DELETE /api/merge-train/auto-merge/:id against the dashboard. The route needs the dashboard’s internal token (the x-overdeck-internal-token header) or a dashboard session.
3. The CLI:
   pan merge cancel PAN-123
   
   This calls the DELETE endpoint, removes the entry from the pending list, drops any waiting entry for the issue from the project merge queue, and emits an auto-merge cancelled for PAN-123 TTS announcement so the operator knows the abort took effect.

​

Queue interaction

​

Inspecting state

# Pending entries currently in cooldown
curl http://localhost:3011/api/merge-train/auto-merge/pending

# Rows that failed or were blocked during the executor tick
curl http://localhost:3011/api/merge-train/auto-merge/problems

​

Failure handling

​

Related

• GET / POST /api/merge-train/config: read and write require_uat_before_merge, merge_train_enabled, and auto_pickup_backlog (no CLI)
• pan merge cancel <id> — cancel a pending auto-merge
• roles/flywheel.md — the orchestrator’s contract; references the toggle when deciding whether to call the scheduler vs. emitting a merge suggestion for human action.