Brewtools:Deploy

[DICT: P=Phase, EXEC=EXECUTE using Bash tool, AUQ=AskUserQuestion, WF=workflow, CFG=config, REF=references, GH=gh CLI, TPL=template, LOPS=deploy-local-ops.sh]

GitHub Actions Deployment

Manage GitHub Actions — WFs, releases, GHCR, CI/CD with safety gates + persistent CFG.

<instructions>

Robustness Rules (MANDATORY — ALL phases)

Fail-Fast

Loop Protection

Timeouts

Fallback Strategy

1. Report exact error: script name, exit code, stderr 2. Attempt same op manually (inline Bash) — scripts are helpers, not gatekeepers 3. If manual also fails → report both + AUQ what to do 4. !=silently swallow errors or continue with stale/missing data

Error Reporting (MANDATORY)

On ANY failure — before stopping or AUQ:

SCRIPT_ERROR: <name>
EXIT_CODE: <code>
STDERR: <message>
PHASE: <current>
ACTION: <attempted>
FALLBACK: <next OR "asking user">

Silent failures = bugs.

---

P0: Mode Detection (MANDATORY FIRST STEP)

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/detect-mode.sh" "$ARGUMENTS"

Output: ARGS: [...] MODE: [...]

---

P1: Environment + CFG Check (ALL modes before branching)

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/gh-env-check.sh" && echo "OK env-check" || echo "FAILED env-check"

STOP if FAILED — fix GH env before continuing.

Parse key=value: GH CLI version, auth status, repo info, secrets count.

Load Existing CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" list 2>/dev/null || echo "NO_CONFIG"

Read CLAUDE.local.md — check ## GitHub Config + ## Workflows: sections.

---

P2: Setup

Step 1: Verify GH Auth

EXEC:

gh auth status 2>&1 && echo "OK auth" || echo "FAILED auth"

If FAILED → instruct: gh auth login

Step 2: Detect Repo

EXEC:

gh repo view --json owner,name,url,defaultBranchRef,visibility 2>/dev/null && echo "OK repo" || echo "FAILED repo"

Step 3: Check Secrets

EXEC:

gh secret list 2>/dev/null && echo "OK secrets" || echo "FAILED secrets"

Step 4: Check SSH Integration

EXEC:

grep -q "^## SSH Servers" CLAUDE.local.md 2>/dev/null && echo "SSH_SERVERS=exists" || echo "SSH_SERVERS=missing"

Step 5: Discover WFs

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/workflow-discover.sh" && echo "OK discovery" || echo "FAILED discovery"

Step 6: Persist CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" add-github "OWNER" "REPO" "ghcr.io" && echo "OK add-github" || echo "FAILED add-github"

Replace OWNER + REPO with values from Step 2. EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" add-workflows && echo "OK add-workflows" || echo "FAILED add-workflows"

Step 7: Gitignore

EXEC:

grep -q "CLAUDE.local.md" .gitignore 2>/dev/null && echo "EXISTS" || (echo "CLAUDE.local.md" >> .gitignore && echo "ADDED")

Step 8: Generate deploy-admin Agent

EXEC:

cat "${CLAUDE_SKILL_DIR}/templates/deploy-admin-agent.md.template"

Replace placeholders: {{GITHUB_CONFIG}}=GH CFG table | {{WORKFLOW_INVENTORY}}=WFs table | {{SERVER_TARGETS}}=SSH Servers (or "No SSH servers CFG") | {{SECRETS_LIST}}=secret names | {{LAST_UPDATED}}=current ISO timestamp. Write to .claude/agents/deploy-admin.md.

---

P3: Create WF

Step 1: Load TPLs

Read REF/workflow-templates.md for WF patterns.

Step 2: Determine Type

AUQ: "What type of GitHub Actions WF?"

• "Build + Push to GHCR" — Docker image → GHCR
• "Deploy to VPS" — SSH to remote server
• "Release" — GitHub Release from tag push
• "Security Scan" — dependency/code scan with SARIF
• "Custom" — describe needs

Step 3: Generate YAML

1. Generate WF YAML with project-specific values 2. Write to .github/workflows/<name>.yml 3. Validate YAML structure

EXEC:

mkdir -p .github/workflows && echo "OK dir" || echo "FAILED dir"

Write WF file via Write tool.

Step 4: Update CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" update-workflows && echo "OK update" || echo "FAILED update"

---

P4: Release (CRITICAL)

Read REF/safety-rules.md + REF/release-best-practices.md first.

Step 1: Determine Version

EXEC:

git describe --tags --abbrev=0 2>/dev/null || echo "NO_TAGS"

EXEC:

git log --oneline $(git describe --tags --abbrev=0 2>/dev/null || echo "HEAD~10")..HEAD 2>/dev/null | head -20

Suggest semver bump (patch/minor/major) based on commits.

Step 2: Bump Version

EXEC:

bash .claude/scripts/bump-version.sh X.Y.Z && echo "OK bump" || echo "FAILED bump"

Step 3: Auto-generate Changelog

Analyze commits since last tag. Group by type (Added/Changed/Fixed).

Step 4: Update RELEASE-NOTES.md

Add at top:

## vX.Y.Z (YYYY-MM-DD)
> Docs: [page](https://doc-claude.brewcode.app/plugin/path/) | [page2](...)
### brewcode
#### Added / Changed / Fixed
- **category:** description

Step 5: Confirmation Gate

AUQ: "Ready to release vX.Y.Z:\n\n[changelog preview]\n\nThis will:\n1. Commit version bump + changelog\n2. Create tag vX.Y.Z\n3. Push to remote (triggers CI)\n4. Run update-plugin.sh\n\nProceed?" Options: "Yes, release" | "Edit changelog first" | "Cancel"

Step 6: Commit + Tag + Push

EXEC:

git add -A && git commit -m "vX.Y.Z: <summary>" && echo "OK commit" || echo "FAILED commit"

EXEC:

git tag vX.Y.Z && echo "OK tag" || echo "FAILED tag"

EXEC:

git push && git push --tags && echo "OK push" || echo "FAILED push"

Step 7: Post-Release

EXEC:

bash .claude/scripts/update-plugin.sh && echo "OK update-plugin" || echo "FAILED update-plugin"

Step 8: Monitor CI

EXEC:

timeout 60 gh run list -L 3 --json workflowName,status,conclusion,createdAt 2>/dev/null && echo "OK runs" || echo "FAILED runs"

Wait for runs triggered by tag push. Report status.

Step 9: Verify Release

EXEC:

gh release view vX.Y.Z --json tagName,name,isDraft,createdAt 2>/dev/null && echo "OK release" || echo "FAILED release"

EXEC:

grep '"matcher"' ~/.claude/plugins/cache/claude-brewcode/brewcode/X.Y.Z/hooks/hooks.json 2>/dev/null && echo "OK cache" || echo "FAILED cache"

---

P5: Deploy

Step 1: Load Safety Rules

Read REF/safety-rules.md.

Step 2: List Deployable WFs

EXEC:

gh workflow list --json name,state,id --jq '.[] | select(.state == "active")' 2>/dev/null && echo "OK list" || echo "FAILED list"

Step 3: Select WF

If multiple: AUQ to select. If $ARGUMENTS specifies WF → use that.

Step 4: Confirmation Gate

AUQ: "About to trigger WF:\n\n WF: [name]\n Branch: [branch]\n Inputs: [if any]\n\nClassification: SERVICE\nProceed?" Options: "Yes, deploy" | "Cancel"

Step 5: Trigger

EXEC:

timeout 30 gh workflow run "WORKFLOW_FILE" --ref BRANCH && echo "OK trigger" || echo "FAILED trigger"

Step 6: Watch Run

EXEC:

sleep 5 && timeout 300 gh run list -w "WORKFLOW_FILE" -L 1 --json databaseId,status,conclusion --jq '.[0]' 2>/dev/null && echo "OK run" || echo "FAILED run"

Poll until complete or timeout.

Step 7: VPS Health Check (if deploy target is VPS + CLAUDE.local.md has SSH CFG)

EXEC:

curl -sf -o /dev/null -w "%{http_code}" "HEALTH_URL" && echo "OK health" || echo "FAILED health"

---

P6: Monitor

Step 1: WF Runs

EXEC:

timeout 30 gh run list -L 10 --json workflowName,status,conclusion,createdAt,headBranch,event 2>/dev/null && echo "OK runs" || echo "FAILED runs"

Step 2: WF Status

EXEC:

timeout 30 gh workflow list --json name,state,id 2>/dev/null && echo "OK workflows" || echo "FAILED workflows"

Step 3: Releases

EXEC:

timeout 30 gh release list -L 5 2>/dev/null && echo "OK releases" || echo "FAILED releases"

Step 4: Failed Run Logs (if conclusion=failure found)

EXEC:

timeout 30 gh run view RUN_ID --log-failed 2>/dev/null | tail -50 && echo "OK logs" || echo "FAILED logs"

Replace RUN_ID with failed run's databaseId.

Step 5: Update CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" update-workflows && echo "OK update" || echo "FAILED update"

---

Mode: update-agent

Re-discover all WFs + refresh deploy-admin agent.

Step 1: Discover

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/workflow-discover.sh" && echo "OK discovery" || echo "FAILED discovery"

Step 2: Update CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" update-workflows && echo "OK update" || echo "FAILED update"

Step 3: Re-read CFG

EXEC:

bash "${CLAUDE_SKILL_DIR}/scripts/${LOPS}" read-github 2>/dev/null

Step 4: Regenerate Agent

Read TPL, replace placeholders with fresh data, write to .claude/agents/deploy-admin.md. Set {{LAST_UPDATED}} = current timestamp. Report what changed.

</instructions>

---

Output Format

# Deploy [MODE]

## Detection
| Field | Value |
|-------|-------|
| Arguments | `$ARGUMENTS` |
| Mode | `[detected mode]` |

## Environment
| Component | Status |
|-----------|--------|
| gh CLI | [version] |
| Auth | [user] |
| Repo | [owner/name] |
| Secrets | [N CFG] |
| WFs | [N found] |

## Actions Taken
- [action 1]
- [action 2]

## Status
[success / partial / failed]

Release Best Practices

Release flow, semver rules, changelog conventions for this project.

Semver Rules

Release Flow (this project)

1. bump-version.sh X.Y.Z     → Updates ALL 6 version files
2. Update RELEASE-NOTES.md    → Add changelog section
3. git add + commit           → "vX.Y.Z: <summary>"
4. git tag vX.Y.Z             → Create tag
5. git push && push --tags    → Push to remote (triggers CI)
6. update-plugin.sh           → Refresh local plugin cache
7. Verify CI                  → gh run list -L 3 (all green)
8. Verify cache               → grep matcher in hooks.json

Version Files (CRITICAL — ALL must match)

NEVER edit versions manually. ALWAYS use bash .claude/scripts/bump-version.sh X.Y.Z

RELEASE-NOTES.md Format

## vX.Y.Z (YYYY-MM-DD)

> Docs: [page](https://doc-claude.brewcode.app/plugin/path/) | [page2](...)

### brewcode
#### Added
- **skill:** deploy skill — GitHub Actions deployment with safety gates

#### Changed
- **hook:** improved pre-compact knowledge extraction

#### Fixed
- **script:** bump-version.sh handles missing files gracefully

Rules

Changelog Generation

From Commits

Analyze commits since last tag:

git log --oneline $(git describe --tags --abbrev=0)..HEAD

Type Mapping

Plugin Detection

Detect which plugin is affected from file paths:

Tag Conventions

CI Triggers

Post-Release Verification

Emergency Rollback

If release has critical issues:

1. Do NOT delete the tag (breaks references) 2. Fix forward: create patch release vX.Y.(Z+1) 3. If CI broken: gh workflow run "Deploy Docs" -f image_tag=PREVIOUS_VERSION

GitHub Command Safety Classification

Reference for command classification and confirmation gates.

Classification Levels

READ Commands (free)

CREATE Commands (free)

MODIFY Commands (confirm)

SERVICE Commands (confirm)

DELETE Commands (always confirm)

PRIVILEGE Commands (always confirm)

Compound Command Rules

Confirmation Message Format

MODIFY/SERVICE

About to execute:

  [command 1]
  [command 2]

Classification: MODIFY/SERVICE
Repo: [owner/name]
Branch: [branch]
Proceed?

DELETE/PRIVILEGE

WARNING: DESTRUCTIVE action on [owner/name]:

  [command 1] -- [what it deletes/changes]

Classification: DELETE/PRIVILEGE
This cannot be undone.
Proceed?

Emergency Stop

If any command returns unexpected output suggesting:

• Wrong repository (owner/name mismatch)
• Production branch when expecting staging/dev
• Force push to main/master
• Deleting a non-draft release with downloads
• Tag already exists on remote with different commit

STOP immediately. Report findings. Ask user to confirm before continuing.

GitHub Actions Workflow Templates

Based on real workflows from this repository. Replace {{PLACEHOLDERS}} with project values.

Template 1: Build + Push to GHCR

Based on: docs.yml -- builds Docker image, pushes to GitHub Container Registry.

Trigger: Tag push v*.*.* + branch pushes (except main). Key steps: Checkout, compute tags, Docker Buildx, GHCR login, build+push, summary.

name: {{WORKFLOW_NAME}}

on:
  push:
    tags:
      - "v*.*.*"
    branches-ignore:
      - main

permissions:
  contents: read
  packages: write

concurrency:
  group: {{CONCURRENCY_GROUP}}-${{ github.ref }}
  cancel-in-progress: true

env:
  IMAGE: ghcr.io/{{OWNER}}/{{IMAGE_NAME}}

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Compute image tags
        id: meta
        run: |
          if [[ "$GITHUB_REF" == refs/tags/v* ]]; then
            VERSION="${GITHUB_REF_NAME#v}"
            echo "tags=${IMAGE}:${VERSION},${IMAGE}:latest" >> "$GITHUB_OUTPUT"
            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          else
            BRANCH="${GITHUB_REF_NAME}"
            BRANCH_SAFE=$(echo "$BRANCH" | sed 's/[^a-zA-Z0-9._-]/-/g')
            DESC=$(git describe --tags --long --match "v*.*.*" 2>/dev/null || echo "0.0.0-0-g$(git rev-parse --short HEAD)")
            BASE_VERSION=$(echo "$DESC" | sed 's/^v//' | sed 's/-.*//')
            COMMITS_AFTER=$(echo "$DESC" | sed 's/.*-\([0-9]*\)-g.*/\1/')
            TAG="${BASE_VERSION}-${BRANCH_SAFE}-${COMMITS_AFTER}"
            echo "tags=${IMAGE}:${TAG}" >> "$GITHUB_OUTPUT"
            echo "version=${TAG}" >> "$GITHUB_OUTPUT"
          fi

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to GHCR
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v7
        with:
          context: {{DOCKER_CONTEXT}}
          platforms: linux/amd64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          build-args: VERSION=${{ steps.meta.outputs.version }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Summary
        run: |
          echo "### Image pushed" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "**Version:** \`${{ steps.meta.outputs.version }}\`" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "**Tags:**" >> "$GITHUB_STEP_SUMMARY"
          IFS=',' read -ra TAGS <<< "${{ steps.meta.outputs.tags }}"
          for tag in "${TAGS[@]}"; do
            echo "- \`${tag}\`" >> "$GITHUB_STEP_SUMMARY"
          done

Placeholders:

---

Template 2: Deploy to VPS

Based on: deploy-docs.yml -- deploys via SSH after upstream build completes.

Trigger: workflow_run (after build) + workflow_dispatch (manual). Key steps: Compute tag, SCP deploy files, SSH deploy script, health check, rollback.

name: {{WORKFLOW_NAME}}

on:
  workflow_run:
    workflows: ["{{UPSTREAM_WORKFLOW}}"]
    types: [completed]
  workflow_dispatch:
    inputs:
      image_tag:
        description: "Docker image tag to deploy"
        required: true
        default: "latest"

concurrency:
  group: {{CONCURRENCY_GROUP}}
  cancel-in-progress: false

env:
  HEALTH_URL: {{HEALTH_CHECK_URL}}

permissions:
  contents: read
  deployments: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: >
      github.event_name == 'workflow_dispatch' ||
      github.event.workflow_run.conclusion == 'success'

    steps:
      - name: Checkout
        uses: actions/checkout@v6
        with:
          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
          fetch-depth: 0

      - name: Compute image tag
        id: tag
        run: |
          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            echo "value=${{ inputs.image_tag }}" >> "$GITHUB_OUTPUT"
          else
            REF="${{ github.event.workflow_run.head_branch || github.ref_name }}"
            if [[ "$REF" =~ ^v[0-9]+\.[0-9]+\.[0-9]+ ]]; then
              echo "value=${REF#v}" >> "$GITHUB_OUTPUT"
            else
              BRANCH_SAFE=$(echo "$REF" | sed 's/[^a-zA-Z0-9._-]/-/g')
              DESC=$(git describe --tags --long --match "v*.*.*" 2>/dev/null || echo "0.0.0-0-g$(git rev-parse --short HEAD)")
              BASE_VERSION=$(echo "$DESC" | sed 's/^v//' | sed 's/-.*//')
              COMMITS_AFTER=$(echo "$DESC" | sed 's/.*-\([0-9]*\)-g.*/\1/')
              echo "value=${BASE_VERSION}-${BRANCH_SAFE}-${COMMITS_AFTER}" >> "$GITHUB_OUTPUT"
            fi
          fi

      - name: Create deployment
        id: deployment
        uses: actions/github-script@v8
        with:
          script: |
            const deployment = await github.rest.repos.createDeployment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              ref: context.sha,
              environment: '{{ENVIRONMENT}}',
              auto_merge: false,
              required_contexts: [],
              description: `Deploy {{SERVICE}} v${{ steps.tag.outputs.value }}`,
            });
            await github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              deployment_id: deployment.data.id,
              state: 'in_progress',
              log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
            });
            return deployment.data.id;

      - name: Copy deploy files to VPS
        uses: appleboy/scp-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          source: "{{DEPLOY_FILES_SOURCE}}"
          target: /tmp/{{DEPLOY_SYNC_DIR}}
          strip_components: {{STRIP_COMPONENTS}}

      - name: Deploy service
        uses: appleboy/ssh-action@v1
        env:
          TAG: ${{ steps.tag.outputs.value }}
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          envs: TAG
          script: |
            set -euo pipefail

            DEPLOY_PATH={{VPS_DEPLOY_PATH}}

            cp /tmp/{{DEPLOY_SYNC_DIR}}/* "$DEPLOY_PATH/" 2>/dev/null || true
            rm -rf /tmp/{{DEPLOY_SYNC_DIR}}

            cd "$DEPLOY_PATH"

            [ -f .env ] && cp .env .env.bak || touch .env.bak

            if grep -q "^{{TAG_VAR}}=" .env 2>/dev/null; then
              sed -i "s/^{{TAG_VAR}}=.*/{{TAG_VAR}}=${TAG}/" .env
            else
              echo "{{TAG_VAR}}=${TAG}" >> .env
            fi

            for attempt in $(seq 1 10); do
              if docker compose pull {{SERVICE_NAME}} 2>&1; then
                break
              fi
              if [ "$attempt" -eq 10 ]; then
                echo "Failed to pull image after 10 attempts"
                exit 1
              fi
              echo "Image not available yet, retrying in 15s... (attempt $attempt/10)"
              sleep 15
            done

            docker compose up -d --no-deps --force-recreate {{SERVICE_NAME}}

            for i in $(seq 1 10); do
              if curl -sf -o /dev/null "{{INTERNAL_HEALTH_URL}}"; then
                echo "Health check passed (attempt $i)"
                exit 0
              fi
              echo "Waiting for service... (attempt $i/10)"
              sleep 5
            done

            echo "Health check failed, rolling back..."
            cp .env.bak .env
            docker compose pull {{SERVICE_NAME}}
            docker compose up -d --no-deps --force-recreate {{SERVICE_NAME}}
            exit 1

      - name: Verify from runner
        run: |
          for i in $(seq 1 5); do
            STATUS=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL" || true)
            if [[ "$STATUS" == "200" ]]; then
              echo "External health check passed (HTTP $STATUS)"
              exit 0
            fi
            echo "Waiting... (attempt $i/5, HTTP $STATUS)"
            sleep 5
          done
          echo "::warning::External health check did not return 200"

      - name: Update deployment (success)
        if: success()
        uses: actions/github-script@v8
        with:
          script: |
            await github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              deployment_id: ${{ steps.deployment.outputs.result }},
              state: 'success',
              environment_url: '{{PUBLIC_URL}}',
              log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
            });

      - name: Update deployment (failure)
        if: failure()
        uses: actions/github-script@v8
        with:
          script: |
            const id = ${{ steps.deployment.outputs.result || 0 }};
            if (!id) return;
            await github.rest.repos.createDeploymentStatus({
              owner: context.repo.owner,
              repo: context.repo.repo,
              deployment_id: id,
              state: 'failure',
              log_url: `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`,
            });

      - name: Summary
        if: always()
        run: |
          echo "### Deploy {{SERVICE}}" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "**Tag:** \`${{ steps.tag.outputs.value }}\`" >> "$GITHUB_STEP_SUMMARY"
          echo "**Health:** $HEALTH_URL" >> "$GITHUB_STEP_SUMMARY"

Placeholders:

Required secrets: VPS_HOST, VPS_USER, VPS_SSH_KEY

---

Template 3: Release

Based on: release.yml -- creates GitHub Release from tag push, extracts changelog.

Trigger: Tag push v*.*.* Key steps: Extract changelog from RELEASE-NOTES.md, create GitHub Release.

name: Release

on:
  push:
    tags:
      - "v*.*.*"

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          sparse-checkout: RELEASE-NOTES.md

      - name: Extract changelog for tag version
        id: changelog
        run: |
          TAG="${GITHUB_REF_NAME}"
          VERSION="${TAG#v}"
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"

          RELEASE_NOTES="RELEASE-NOTES.md"

          if [ ! -f "$RELEASE_NOTES" ]; then
            echo "::error::${RELEASE_NOTES} not found"
            exit 1
          fi

          BODY=$(awk -v ver="$VERSION" '
            BEGIN { found=0 }
            $0 ~ "^## (\\[" ver "\\]|v?" ver ")([^0-9.]|$)" {
              found=1
              print
              next
            }
            found && $0 ~ "^## (\\[|v?[0-9])" { exit }
            found && /^---[[:space:]]*$/ { exit }
            found { print }
          ' "$RELEASE_NOTES")

          if [ -z "$BODY" ]; then
            echo "::error::No changelog section found for version ${VERSION} in ${RELEASE_NOTES}"
            exit 1
          fi

          echo "$BODY" > /tmp/release-body.md

          # Append install instructions
          printf '\n---\n\n## Quick Install\n\n```bash\n# Add marketplace\nclaude plugin marketplace add https://github.com/{{OWNER}}/{{REPO}}\n\n# Install plugins\n{{INSTALL_COMMANDS}}\n```\n\n## Already installed? Update\n\n```bash\nclaude plugin marketplace update {{REPO}}\n{{UPDATE_COMMANDS}}\n```\n' >> /tmp/release-body.md

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          tag_name: ${{ steps.changelog.outputs.tag }}
          name: ${{ steps.changelog.outputs.tag }}
          body_path: /tmp/release-body.md
          draft: false
          prerelease: false

Placeholders:

---

Template 4: Security Scan

Generic template for dependency/code scanning.

Trigger: Push to main + PRs + weekly schedule. Key steps: Checkout, run scanner, upload SARIF, summary.

name: Security Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 6 * * 1"

permissions:
  contents: read
  security-events: write

concurrency:
  group: security-${{ github.ref }}
  cancel-in-progress: true

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Run {{SCANNER_NAME}}
        uses: {{SCANNER_ACTION}}
        with:
          {{SCANNER_INPUTS}}

      - name: Upload SARIF
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: {{SARIF_PATH}}

      - name: Summary
        if: always()
        run: |
          echo "### Security Scan" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "**Scanner:** {{SCANNER_NAME}}" >> "$GITHUB_STEP_SUMMARY"
          echo "**Branch:** ${{ github.ref_name }}" >> "$GITHUB_STEP_SUMMARY"

Placeholders: