deploy — GitHub Actions CI/CD

Quick reference

Field	Value
Command	/brewtools:deploy
Arguments	<task description> or mode keyword
Modes	setup · create · release · deploy · monitor · update-agent
Agent	deploy-admin — auto-delegated for complex ops
Config	CLAUDE.local.md (gitignored)
Model	opus
Tools	Read, Write, Edit, Bash, Task, AskUserQuestion, Glob, Grep

When to use

• First-time setup — setup detects repo, enumerates workflows, writes CLAUDE.local.md, generates the deploy-admin agent
• New workflow — create generates YAML from 4 battle-tested templates (Build+GHCR, Deploy VPS, Release, Security Scan)
• Release a version — release covers bump → changelog → commit → tag → push → CI verification in one shot
• Trigger a deployment — deploy selects a workflow_dispatch workflow, confirms, triggers, monitors run
• Check CI status — monitor shows recent runs, workflow states, latest releases, failed run logs
• Refresh agent — update-agent re-discovers workflows and regenerates the deploy-admin agent with current data

Examples

# First-time GitHub integration setup
/brewtools:deploy setup

# Release patch version — bump, changelog, tag, push, verify CI
/brewtools:deploy release patch

# Release a specific version
/brewtools:deploy release v3.5.0

# Create a Docker build workflow for GHCR
/brewtools:deploy create new build workflow for ghcr.io

# Trigger a deployment and watch progress
/brewtools:deploy trigger deploy-docs workflow

Flow

Release mode knows nothing about your repo until it looks

Nothing in the release path is hardcoded to a particular repo layout:

Step	Behavior
Bump	BUMP_SCRIPT found → run it. none + version files obvious → edit every version file the repo actually has (package.json, pyproject.toml, gradle.properties, Cargo.toml, …) to the same X.Y.Z. none + unclear → ask which files carry the version
Changelog	Written into the CHANGELOG file from Step 0, matching the heading style already in that file. none → the summary goes into the tag/release body instead
Post-release	Runs only if POST_SCRIPT was found; otherwise skipped and reported as “no post-release script”
Verify	Checks whichever artifact the project actually publishes — container image, npm/PyPI package, a live /version endpoint, a plugin cache entry. Nothing published → “no external artifact to verify”, not a failure

The multi-package flow with its own bump script, plugin-cache verification and doc links lives in references/release-best-practices.md as a clearly labelled worked EXAMPLE — a pattern to adapt, not commands to run.

Delegation

Every spawn prompt carries six fields. A bare one-line task is never enough:

Field	Content
GOAL	the overall task and why it exists — the point beyond the file edit
ROLE	what this agent owns; what it must NOT touch
SCOPE	exact paths and commands in bounds + explicit out-of-bounds
CONTEXT	what is already done, by whom, what runs in parallel — trimmed to what this agent needs
CONSUMER	who or what uses the result next, and the shape it must fit
DONE	acceptance criteria + the exact report shape expected back

Safety gates are not delegable. AskUserQuestion is stripped from every subagent at runtime, so a spawned deploy-admin cannot confirm anything — the confirmation gates on release (P4 Step 3) and deploy (P5 Step 4) stay in this skill, in the main conversation. A delegated agent finishes all non-destructive work and ends its return with an ## APPROVAL REQUIRED block instead — one envelope per destructive operation (COMMAND / HOST / EFFECT / ROLLBACK / EVIDENCE / PRECONDITION), or the literal APPROVAL REQUIRED: none. This skill shows the envelopes to the user, then re-spawns the agent with APPROVED: A1 A3 in the prompt — the only authorization a subagent may act on.

Workflows, secrets, and internals

Safety classification

Class	Operations	Confirmation
READ	gh run list, gh workflow list, gh release view, gh secret list	None
CREATE	Create workflow YAML, gh release create --draft	None (non-destructive)
MODIFY	Edit workflow, gh secret set, git commit/tag	Required
SERVICE	gh workflow run, gh run rerun, git push	Required
DELETE	gh release delete, gh run cancel, remove workflow file	Always required
PRIVILEGE	gh secret delete, branch protection, gh workflow disable	Always required

Workflow templates

Template	Trigger	Description
Build + Push GHCR	tag / branch	Multi-platform Docker build, push to ghcr.io
Deploy to VPS	workflow_dispatch	SCP + SSH deploy, health check, rollback
Release	tag v*.*.*	Extract changelog, create GitHub Release with assets
Security Scan	push / PR	CodeQL / Gitleaks / Semgrep with SARIF upload

Configuration storage

GitHub config and workflow inventory are stored in CLAUDE.local.md at the project root. This file is gitignored automatically during setup. Secret names are stored for reference; secret values are never read or written.

The deploy-admin agent is generated with workflow inventory, GitHub config, and SSH server targets baked into its prompt. Run update-agent mode after workflow or config changes to refresh it.

SSH integration

The skill reads SSH server inventory from CLAUDE.local.md (written by the ssh skill) for VPS deployment targets and post-deploy health checks. Run /brewtools:ssh setup first if you need VPS deployments.

Robustness rules

Every Bash call uses && echo "OK" || echo "FAILED" with fail-fast logic. Max 2 retries per operation, max 15 gh calls per invocation. Every bounded call runs through a shared watchdog (real timeout/gtimeout when installed, a bash fallback otherwise — GNU timeout is Homebrew-only on macOS): 30 s for gh commands, 15 min for gh run watch. CI runs are correlated by the pushed commit’s headSha, not by reading the newest rows of gh run list — a bare “latest run” can belong to a concurrent push. A run that can’t be matched or times out is reported as such, never silently treated as success.

Troubleshooting

Issue	Solution
gh CLI not installed	Install from https://cli.github.com/
Not authenticated	Run ! gh auth login in Claude Code terminal
Insufficient token scopes	Re-authenticate: ! gh auth login -s repo,workflow,write:packages
Workflow not triggering	Check trigger config in workflow YAML, verify branch/tag pattern
Release CI failed	/brewtools:deploy monitor to view failed run logs
VPS deploy failed	Check SSH connectivity with /brewtools:ssh connect to server-name