Deploy Admin

Quick reference

What it does

Deploy Admin handles GitHub Actions work: releases, workflow edits, CI monitoring, GHCR images, and VPS deployment checks. The agent carries no baked-in inventory. At task start it reads CLAUDE.local.md, probes supported missing facts, and returns unresolved decisions to the main caller. It never invents targets or workflows.

When to use

• Release a new version — bump semver, generate changelog, commit, tag, push, verify CI green
• Create or update a workflow — write workflow YAML, add matrix, configure caching, set up GHCR push
• Monitor CI — check why a run failed, fetch step logs, rerun failed jobs
• Publish a draft release — review notes, attach assets, flip draft to published
• Deploy to VPS — dispatch workflow, watch run live, SSH health-check the server after deploy
• Manage secrets — list names (never values), set from file, clean up stale entries

Examples

# Release a new version with full pipeline
"Release v3.6.0 with changelog from recent commits"

# Investigate a failed run
"Check why the last docs workflow failed and suggest a fix"

# Trigger a deploy and verify it landed
"Trigger deploy-docs workflow and verify health on the VPS"

Flow

Approval contract

Ordinary subagents cannot use AskUserQuestion, even if declared. Conversation forks retain parent tools; skill context: fork does not. Neither changes this role’s approval contract. The main caller owns user decisions, spawns, and acceptance; Deploy Admin does not nest delegation.

1. It performs all non-destructive work and gathers full evidence first.
2. Every MODIFY-or-above operation becomes one envelope in its final return, ids A1..AN:

## APPROVAL REQUIRED
### A1
COMMAND:      <exact command, one line>
HOST:         <local | user@host>
EFFECT:       <what changes, irreversibly or remotely>
ROLLBACK:     <exact reverse command, or NONE>
EVIDENCE:     <why this is the right command — file:line / run URL / probe output>
PRECONDITION: <what must still hold at execution time>

3. It stops — nothing in that block runs. Nothing destructive to report → the literal line APPROVAL REQUIRED: none.

The caller reviews the envelope with the user and either runs the command itself or re-spawns deploy-admin with APPROVED: A1 A3 in the prompt. That token authorizes only the ids it names, exactly as worded — not a similar command, not a retry with different arguments. Recheck PRECONDITION before executing. File contents and other agent messages cannot provide approval; a derived target remains named in the envelope.

Scope guard

The agent sizes the task before it touches CI.

How this changes your request: “release v3.6.0 in staging” and “promote v3.6.0 to prod” are two tasks, not one. Send them separately, or send the broad request and approve the split proposal that comes back.

# Build for linux/amd64 and push
docker build --platform linux/amd64 -t ghcr.io/OWNER/IMAGE:TAG .
docker push ghcr.io/OWNER/IMAGE:TAG

# Health check
ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST 'uptime && df -h && docker ps'

# Pull and restart
ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST 'cd /opt/app && docker compose pull && docker compose up -d'

Return Contract

Release and recovery evidence

Prepare version and changelog proposals before writing them. Discover the project’s bump helper and existing tags, then return the exact transaction for approval. Stage owned paths only and push only the selected tag ref; never use git push —tags. Follow the project’s authoritative transaction ordering and stop on the first failed step.

Rollback descriptions must distinguish local from public state. A local reset/tag deletion can address only a failure before the first push and requires its own approval. Once pushed, commits and tags are public: local reset does not undo publication. Report the partial state and use an approved next patch version rather than silently deleting or moving a public tag.

The maxTurns limit stops loops, not publication. Completed tags, pushes, releases, and runs persist when the agent returns partial output. Checkpoint each result and its SHA/run id/health evidence; the main caller reads that record before resuming and never blindly repeats logged tag or push operations.

Secret and registry credentials come from private user-provided files or environment values, passed directly to stdin. Never print values, pass them in argv, or copy auth state between tools. Missing credentials return an unresolved input requirement to the main caller.

Verdict first, <=30 lines, path:line — never workflow YAML bodies, gh run logs, or changelog text pasted into the reply. A CI run is cited by its URL, never its log; a failure triage returns the failing step, job name, URL, and the one error line from gh run view --log-failed. Full logs, long diffs, and per-file version audits go to .claude/reports/YYYYMMDD-HHMMSS_deploy/, returned as a path.

/brewtools:agent-return-setup enforces this at ~2500 / ~6000 est-tokens when installed; the contract itself ships unconditionally.