ADR-0025: Opt-in Auto Gates for Headless Autopilot¶
Metadata¶
Status: Accepted (2026-10-20) · Date: 2026-10-20 · Deciders: nguyenhuuca · Tags: ci, agents, security, workflow Related: amends ADR-0022 D1 (both gates human) and D4 (only one secret)
Context¶
- Headless autopilot (ADR-0022) stops twice for the owner:
/approveat Gate 1 and a merge at Gate 2. - The owner wants small issues to go through when they are busy, with no approval.
- Two GitHub limits shape the design:
- Comments posted with the job token start no workflows, so a bot
/approvecannot start the build job.workflow_dispatchis the exception: the job token can start it. - A merge made with the job token does not start the push-to-
maindeploy CI. The merge needs another token.
- Comments posted with the job token start no workflows, so a bot
- The repo is public, so the checks that decide a merge must not depend on what the model says.
Decision¶
D1. Opt-in labels on the issue¶
Label (added with autopilot) |
Gate 1 | Gate 2 |
|---|---|---|
| none | /approve |
owner merges |
autopilot:auto-merge |
/approve |
automatic |
autopilot:auto |
automatic | automatic |
- The labels only change gates.
autopilotis still the only label that starts a run. - The issue author check from ADR-0022 D2 still applies. In this repo only the owner can add labels.
D2. Auto Gate 1: the workflow dispatches the build¶
- Marker: the plan job writes
<!-- autopilot:plan-review=approve -->in the PR body, and only when the plan review returnedapprove. - Workflow step: after the plan job, a workflow step checks two things:
- the issue has
autopilot:auto; - the open
autopilot/issue-<N>PR has the marker.
- the issue has
- If both hold: the step runs
gh workflow run autopilot.yml -f pr=<N>and comments on the PR. - If the marker is missing: it comments that Gate 1 stays manual.
- Scope: only a first plan (the
issuesevent) dispatches. A/revisealways waits for/approve. - Who can start the build: the dispatched build accepts the actor
github-actions[bot]or the owner.allowed_bots: "github-actions[bot]"is set only on the build step.
D3. Auto Gate 2: a deterministic merge script¶
scripts/claude-autopilot-merge.sh is always run from origin/main, never from the PR branch. It merges only when every check passes; otherwise it comments the reason and leaves the PR for the owner. The checks:
- The head branch is
autopilot/issue-<N>. - The issue or PR has
autopilot:auto-mergeorautopilot:auto. - The PR is open and not a draft. The model marks it ready only after a code-review
approveand green gates. - No protected paths changed:
.github/,.claude/,CLAUDE.md,AGENTS.md,scripts/claude-*;- Liquibase migrations (
api/src/main/resources/db/changelog/); .env*files.- A schema change always gets a human.
- At most 400 changed lines outside tests and docs (
AUTOPILOT_MAX_LOC). - The gates are re-run by the script, not taken from the model's report:
mvn verifywhenapi/changed;vitest run, lint and build whenwebapp/changed.
- The merge:
gh pr merge --squash --match-head-commit <sha>with the secretAUTOPILOT_MERGE_TOKEN. Its push starts the normal deploy CI.
D4. The merge token¶
- Token type: a fine-grained PAT (or GitHub App token) created and stored by the owner. Scope: this repo only, with
Contents: read/writeandPull requests: read/write. - Exposure: only the auto Gate 2 step sees it, through the step-level
env. The Claude step never does. - If the secret is missing: the script comments and skips. Everything else keeps working.
Consequences¶
- Code reaches prod without a human read. The limits on that are:
- the opt-in label;
- two model reviews;
- the re-run gates;
- no migrations and no workflow or agent-config changes.
- The smoke check after the deploy stays manual (
./api/mock-test.sh). Smoke tests are read-only, so write paths are not covered. - ADR-0022 D4's "both gates are human" no longer holds for labelled issues. A prompt injection in a labelled issue body could now reach prod without anyone seeing it. The owner-only issue check (ADR-0022 D2) is what keeps that out.
- Rolling back =
git revertthe squash commit onmainand push.