Merge approvals

By default the Code Sentinel orchestrator merges a worker's pull request as soon as its checks are green. Merge approval adds a person in between: the orchestrator stops at "green and mergeable" and waits until someone approves. The Approvals page (Project → Approvals) is that waiting list.

Turn it on

There are two switches, and they must agree.

1. 1

   Set your intent in AgentDock

   An admin turns on Settings → General → Merge approval. This tells AgentDock to expect approvals and to show the page's waiting list.

2. 2

   Tell the orchestrator

   Add mergeApproval to the orchestrator block of the project's .code-analyzer-config.json and commit it to the base branch:

   {
     "orchestrator": {
       "base": "main",
       "readyLabel": "cs:ready",
       "mergeApproval": true
     }
   }

   The orchestrator only reads this file. AgentDock never edits committed files, so this step is yours. See Code Sentinel config.

When the two disagree, the settings page and the Approvals page show Merge approval settings disagree with what to change. The dangerous case is AgentDock on and the config off: AgentDock expects approval, but the orchestrator will merge on its own.

The waiting list

A pull request appears when either:

• the plugin emitted pr.awaiting_approval for it (source orchestrator), or
• without plugin events, the config has mergeApproval: true and the slot's pull request is green, mergeable, and reported open by the worker (source inferred).

Each row shows the title, slot, checks, how long it has waited and the source. Click a row to open its sheet:

• Merge summary: the worker's "pull request open" checkpoint, rendered as markdown;
• Head commit: the commit the decision will bind to;
• Diff: additions, deletions and changed files (up to 300 files);
• Checks: each status check;
• earlier decisions on the same pull request and a link to GitHub.

The runner reads these facts with gh pr view and AgentDock caches them for 60 seconds.

Approve or request changes

Operators of the project see two buttons in the sheet. Viewers see the list but no buttons.

• Approve lets the orchestrator merge this pull request.
• Request changes needs a note (up to 4 KB). The note goes back to the worker through the orchestrator.

Either button sends a runner command (pr.approve or pr.requestChanges) that writes one signal file, atomically:

<git-common-dir>/cs-orchestrator/approvals/<pr>.json

{
  "v": 1,
  "pr": 42,
  "decision": "approved",
  "headSha": "9f1c2e7…",
  "by": "[email protected]",
  "at": "2026-10-13T09:12:00.000Z"
}

Recent decisions at the bottom of the page lists who decided what, when, and the note.

A decision binds to the head commit

An approval records the pull request's head SHA at the moment you clicked. If a new commit is pushed afterwards, the approval no longer counts: the row returns to waiting, its status reads "voided (new push)", and the signal file is rewritten with decision: "stale". You approve the code you saw, not whatever lands later.

AgentDock never merges

AgentDock does not merge pull requests and does not post GitHub reviews. It only writes the signal file. The orchestrator reads it on its next wake and merges (or routes the changes back to the worker). Every approve, request-changes and voided approval is written to the audit log with the actor, pull request, head SHA, decision and note.

From Telegram

If you linked Telegram (see Notifications), a pr.awaiting_approval message carries Approve and Request changes buttons. Each press is checked again from scratch: the chat must be linked to an active user who is an operator or admin on the project. Request changes asks you to reply with the note. Decisions made from Telegram are audited as telegram.approval.

The same plugin caveat at the top of this page applies to decisions taken from Telegram.

Not the same as permission prompts

Merge approval is about merging finished work. A worker that stops on a Claude Code permission prompt is a different thing: it shows as status prompt on the Fleet page and raises a pane.prompt notification. An admin answers it through terminal attach.

Next steps