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	`<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

Mode detection
Parses your argument for mode keywords: setup, create, release, deploy, monitor, update-agent. Empty arg with no existing config → setup; with config → monitor.
Environment check
Verifies gh CLI installation, auth status, token scopes, and repo detection. Reads existing CLAUDE.local.md for 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, adds CLAUDE.local.md to .gitignore, generates deploy-admin agent.
Operation
create — generates workflow YAML from template, writes to .github/workflows/, updates config. release — bump → changelog → RELEASE-NOTES.md → commit → tag → push → update-plugin.sh. deploy — confirms classification, triggers workflow_dispatch, polls run status, runs VPS health check if applicable.
Safety gate
Every gh command 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 monitor mode.

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. On timeout (30 s for gh commands, 5 min for gh run watch) the skill reports and switches to polling or stops with a clear error.

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`

🤖

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.