deploy — GitHub Actions CI/CD
Caution
Every destructive operation requires explicit confirmation. The skill classifies each gh command before executing it — DELETE and PRIVILEGE class operations always prompt. Compound commands are split into individually classified steps.
Tip
Run without args — /brewtools:deploy — and the skill auto-detects mode from context: no config yet → setup; config exists → monitor. For complex multi-step DevOps work the deploy-admin agent is spawned automatically.
Quick reference
| Field | Value |
|---|---|
| Command | /brewtools:deploy |
| Arguments | [prompt] [setup|create|release|deploy|monitor|update-agent] |
| 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, Agent, AskUserQuestion, Glob, Grep |
When to use
- First-time setup —
setupdetects repo, enumerates workflows, writesCLAUDE.local.md, generates thedeploy-adminagent - New workflow —
creategenerates YAML from 4 battle-tested templates (Build+GHCR, Deploy VPS, Release, Security Scan) - Release a version — discover tags and preparation, approve the transaction, then stage → commit → HEAD push → tag → tag-ref push → verify
- Trigger a deployment —
deployselects aworkflow_dispatchworkflow, confirms, triggers, monitors run - Check CI status —
monitorshows recent runs, workflow states, latest releases, failed run logs - Refresh agent —
update-agentre-discovers workflows and regenerates thedeploy-adminagent 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 workflowFlow
- Mode detection
Explicit whole-word mode tokens win; otherwise distinct keyword hits select the mode. Conflicting explicit modes or tied mutating intents require clarification before actions. Empty input uses setup without GitHub Config and monitor when that section exists.
- Environment check
Verifies
ghCLI installation, auth status, token scopes, and repo detection. Reads existingCLAUDE.local.mdfor GitHub config and workflow inventory. - Setup (first run)
Detects owner/repo, enumerates workflows and secrets, checks SSH server targets, writes GitHub config to
CLAUDE.local.md, addsCLAUDE.local.mdto.gitignore, generatesdeploy-adminagent. - Operation
Create proposes workflow configuration. Release discovers project tooling and tags, prepares bump/changelog proposals, and obtains approval before writes. Run the approved chain in project order: stage, commit, HEAD push, tag, and exact tag-ref push. Deploy approves dispatch, resolves the resulting run, and checks deployment health when applicable.
- Safety gate
Every
ghcommand is classified before execution. READ and CREATE run freely. MODIFY, SERVICE, DELETE, and PRIVILEGE always ask for confirmation. Confirmation gates on release and deploy show a preview before any push. - Monitor
Dashboard of recent runs, workflow states, latest releases, and failed run logs — auto-triggered after release/deploy and available standalone via
monitormode.
Release mode knows nothing about your repo until it looks
Note
release runs a Step 0 probe before anything else. It lists .claude/scripts/*.sh, scripts/, the scripts block of package.json and Makefile, and records three values — each defaulting to none:
| Value | What it holds |
|---|---|
BUMP_SCRIPT | a bump/version script, or none |
POST_SCRIPT | a post-release/publish script, or none |
CHANGELOG | CHANGELOG.md, RELEASE-NOTES.md, or none |
none is not a failure. It means that step is skipped or done by hand, and the report says so.
Nothing in the release path is hardcoded to a particular repo layout:
| Step | Behavior |
|---|---|
| Bump | Propose the discovered helper or exact version-file changes before writes; unresolved version carriers require clarification |
| Changelog | Propose changes in the existing heading style before writes; without a changelog file, use the tag/release body |
| 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.
Warning
Local recovery does not undo publication. Before any push, approved local recovery can address a failed commit/tag step. Once HEAD is pushed, the commit is public; once the tag is pushed, consumers may have fetched it. Report partial publication and use an approved next patch version rather than deleting or moving public history.
Delegation
Warning
Every Agent spawn gets one bounded deliverable, roughly five files and ten steps, for one repo/environment. Independent targets are assigned separate owners in parallel.
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 decisions stay with the main caller. Ordinary subagents cannot use AskUserQuestion; conversation forks retain parent tools, but this distinction does not change the project’s approval contract. Deploy Admin gathers evidence and returns exact envelopes with COMMAND, HOST, EFFECT, ROLLBACK, EVIDENCE, and PRECONDITION. The main caller presents them and passes APPROVED ids for exact commands only; execution rechecks preconditions.
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_run / workflow_dispatch | SCP + SSH deploy of release-tag images; pulls via a temporary private Docker config, deleted on exit; health check, rollback |
| Release | tag v*.*.* | Extract changelog, create GitHub Release with assets |
| Security Scan | push / PR | CodeQL / Gitleaks / Semgrep with SARIF upload |
All templates pin runs-on: ubuntu-24.04 (never ubuntu-latest). The Deploy template accepts only images built from a release tag (v*.*.*); a branch-built preview image is rejected before any server copy. The server pull logs in to GHCR with the job token over stdin, so stale server credentials cannot cause denied and the VPS user’s ~/.docker/config.json stays untouched.
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
Release transaction failures retain their nonzero exit status and stop later steps. Emit RELEASED only after every approved step succeeds. Secret setting uses private file/stdin input without printing values or passing them as command arguments.
For deployment provenance, correlate the successful source build’s exact SHA, run id, and attempt with the downstream trigger, actual checkout, and published image. Use bounded version tags or SHA/run/attempt tags and verify labels/digests; mutable aliases do not establish provenance. Report missing linkage or live health checks as unverified rather than treating an unrelated green run as deployment success.
Every Bash call preserves its exit status when reporting OK or FAILED; failure reporting must not turn a failed call into success. 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. The generated deploy-admin agent watches every CI run for the pushed SHA (HEAD and tag pushes each start workflows) to a terminal state. 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 |
deploy-admin agent
The auto-generated agent handles complex multi-step DevOps operations with full workflow inventory context.
SSH skill
Configure SSH server inventory used by deploy for VPS targets and health checks.
GitHub source
Source code, scripts, and workflow templates.
Brewtools overview
All brewtools skills — text, secrets, SSH, deploy, and more.
Updating plugins
/brewtools:plugin-update to check and update the brewcode plugin suite in one command.
See the FAQ for details.