Releasing

Release Workflow

Execute semantic versioning releases or scaffold release infrastructure for projects.

Usage

This skill is invoked when:

• User runs /release command with a version argument
• User runs /release --setup to scaffold release infrastructure

Two Operation Modes

Mode 1: Release (/release <version>)

Validates, prepares, and triggers a GitHub release.

Mode 2: Setup (/release --setup)

Scaffolds release scripts and GitHub Actions workflow into the target project.

Supported Arguments

Parse arguments from user input:

• `<version>`: Version to release (e.g., 1.6.0 or v1.6.0)
• `--setup`: Scaffold release infrastructure into current project
• `--skip-monitor`: Trigger workflow but don't wait for completion

Prerequisites

• gh CLI installed and authenticated (gh auth status)
• Git configured with push access to remote
• CHANGELOG.md with a version entry (use /changelog to generate)
• .github/workflows/release.yml exists (use --setup to create)

Release Flow Steps

Step 1: Parse and Validate Version

VERSION="${1:-}"

# Strip 'v' prefix if present
VERSION="${VERSION#v}"

# Validate semver format
if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "Error: Invalid version format '$VERSION'"
    echo "Expected semantic version (e.g., 1.6.0)"
    exit 1
fi

echo "Releasing version: $VERSION"

Step 2: Pre-flight Checks

# Check CHANGELOG.md entry exists
if ! grep -qE "^## \[$VERSION\]" CHANGELOG.md; then
    echo "Error: No CHANGELOG entry found for version $VERSION"
    echo "Add entry with header: ## [$VERSION] - $(date +%Y-%m-%d)"
    echo "Tip: Use '/changelog' to generate the entry."
    exit 1
fi
echo "CHANGELOG entry found"

# Check release doesn't already exist
if gh release view "v$VERSION" &>/dev/null; then
    echo "Error: Release v$VERSION already exists"
    echo "Delete first: gh release delete v$VERSION --yes"
    exit 1
fi
echo "Release does not exist, proceeding"

Step 3: Add Comparison Link to CHANGELOG.md

REPO_URL=$(gh repo view --json url -q '.url')

# Skip if link already exists
if grep -qE "^\[$VERSION\]:" CHANGELOG.md; then
    echo "Comparison link already exists"
else
    # Find previous version (second version header)
    PREV_VERSION=$(grep -E "^## \[[0-9]+\.[0-9]+\.[0-9]+\]" CHANGELOG.md \
        | head -2 | tail -1 | sed 's/.*\[\([0-9.]*\)\].*/\1/')

    if [[ "$PREV_VERSION" != "$VERSION" ]] && [[ -n "$PREV_VERSION" ]]; then
        COMPARE_LINK="[$VERSION]: $REPO_URL/compare/v$PREV_VERSION...v$VERSION"
    else
        COMPARE_LINK="[$VERSION]: $REPO_URL/releases/tag/v$VERSION"
    fi

    # Update [Unreleased] link and add version link
    sed -i.bak "s|\[Unreleased\]:.*|[Unreleased]: $REPO_URL/compare/v$VERSION...HEAD|" CHANGELOG.md
    sed -i.bak "/^\[Unreleased\]:/a\\
$COMPARE_LINK" CHANGELOG.md
    rm -f CHANGELOG.md.bak

    echo "Added comparison link for $VERSION"
fi

Step 4: Commit and Push CHANGELOG Changes

Check if CHANGELOG.md has uncommitted changes. If so, confirm with the user before committing:

if ! git diff --quiet CHANGELOG.md 2>/dev/null; then
    echo "CHANGELOG.md has uncommitted changes."
    # Ask user: "CHANGELOG.md updated with comparison links. Commit and push to main?"
    # If confirmed:
    git add CHANGELOG.md
    git commit -m "docs: prepare release $VERSION"
    git push origin main
    echo "Changes committed and pushed"
fi

Important: Use conversation to confirm with the user before committing and pushing. Do NOT auto-commit without confirmation.

Step 5: Trigger Release Workflow

echo "Triggering release workflow for v$VERSION..."
gh workflow run release.yml -f version="$VERSION"
echo "Workflow triggered"

Step 6: Monitor Workflow

sleep 5

RUN_ID=$(gh run list --workflow=release.yml --limit=1 --json databaseId -q '.[0].databaseId')
REPO_URL=$(gh repo view --json url -q '.url')

echo "Monitoring workflow run $RUN_ID..."
echo "View at: $REPO_URL/actions/runs/$RUN_ID"

# Poll for completion
while true; do
    STATUS=$(gh run view "$RUN_ID" --json status -q '.status')
    if [[ "$STATUS" == "completed" ]]; then
        CONCLUSION=$(gh run view "$RUN_ID" --json conclusion -q '.conclusion')
        break
    fi
    echo "  Status: $STATUS..."
    sleep 5
done

if [[ "$CONCLUSION" == "success" ]]; then
    echo "Release v$VERSION created successfully!"
    echo "View: $REPO_URL/releases/tag/v$VERSION"
else
    echo "Workflow failed: $CONCLUSION"
    echo "Logs: $REPO_URL/actions/runs/$RUN_ID"
    exit 1
fi

If --skip-monitor is specified, skip this step and report the workflow URL instead.

Setup Mode (--setup)

When --setup is specified, scaffold release infrastructure into the current project.

What Gets Scaffolded

Scaffolding Process

1. Read each template file from this skill's scripts/ and templates/ directories 2. Create target directories (scripts/, .github/workflows/scripts/) 3. Write files to target project locations 4. Set executable permissions (chmod +x) on all shell scripts 5. Verify all files exist 6. Report created files and next steps

# Create directories
mkdir -p scripts
mkdir -p .github/workflows/scripts

# Set permissions after writing files
chmod +x scripts/release.sh
chmod +x .github/workflows/scripts/validate-changelog.sh
chmod +x .github/workflows/scripts/extract-release-notes.sh
chmod +x .github/workflows/scripts/create-github-release.sh

Post-Setup Next Steps

After scaffolding, inform the user: 1. Ensure CHANGELOG.md exists (use /changelog to create) 2. Commit the scaffolded files 3. Run /release <version> to create the first release

Important Notes

• CHANGELOG format: Assumes Keep a Changelog format with ## [VERSION] headers
• Branch: Commits and pushes to the current branch (auto-detected via git rev-parse)
• Integration with /changelog: Use /changelog to generate CHANGELOG entries before releasing
• GitHub CLI required: Must have gh installed and authenticated
• Workflow file: Expects .github/workflows/release.yml (use --setup to create)

Supporting Documentation

• [WORKFLOW.md](WORKFLOW.md) - Detailed 7-phase release process and script template reference
• [EXAMPLES.md](EXAMPLES.md) - Real-world release scenarios including first release, patch release, and setup
• [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues with workflow triggers, CHANGELOG format, and gh CLI
• [templates/release.yml](templates/release.yml) - GitHub Actions workflow template for scaffold setup

Release Skill: Examples

Example 1: Standard Release

Release version 1.6.0 after adding a CHANGELOG entry.

# 1. Generate CHANGELOG entry
/changelog --version 1.6.0

# 2. Execute release
/release 1.6.0

What happens: 1. Validates 1.6.0 is valid semver 2. Checks ## [1.6.0] exists in CHANGELOG.md 3. Checks v1.6.0 release doesn't exist on GitHub 4. Adds comparison link: [1.6.0]: https://github.com/user/repo/compare/v1.5.0...v1.6.0 5. Updates [Unreleased] link to compare/v1.6.0...HEAD 6. Asks to commit and push CHANGELOG.md changes 7. Triggers release.yml workflow 8. Monitors until completion 9. Reports: Release v1.6.0 created successfully!

Example 2: First Release

Release the initial version of a new project.

# 1. Set up release infrastructure
/release --setup

# 2. Create CHANGELOG.md
/changelog --version 1.0.0

# 3. Commit scaffolded files and CHANGELOG
git add -A && git commit -m "chore: add release infrastructure"
git push origin main

# 4. Execute first release
/release 1.0.0

Comparison link for first release:

[1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Example 3: Patch Release

Quick bug fix release.

# 1. Fix the bug and commit
/commit

# 2. Update CHANGELOG
/changelog --version 1.5.1

# 3. Release
/release 1.5.1

Example 4: Release with v Prefix

The v prefix is automatically stripped.

/release v2.0.0
# Equivalent to: /release 2.0.0

Example 5: Trigger Without Monitoring

Trigger the workflow and return immediately.

/release 1.6.0 --skip-monitor

Output:

Workflow triggered. Skipping monitoring.
View at: https://github.com/user/repo/actions

Example 6: Setup Scaffolding

Scaffold the full release pipeline into a new project.

/release --setup

Files created:

scripts/
└── release.sh                              # Local release orchestrator

.github/
└── workflows/
    ├── release.yml                         # GitHub Actions workflow
    └── scripts/
        ├── validate-changelog.sh           # CHANGELOG validator
        ├── extract-release-notes.sh        # Release notes extractor
        └── create-github-release.sh        # GitHub release creator

Example 7: Using release.sh Directly

After scaffolding, the release script can be run directly from the terminal.

# Interactive mode (prompts for confirmation)
./scripts/release.sh 1.6.0

# Non-interactive mode (for CI)
./scripts/release.sh 1.6.0 --yes

# Skip monitoring
./scripts/release.sh 1.6.0 --yes --skip-monitor

Example 8: CHANGELOG Format Expected

The skill expects Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.6.0] - 2026-03-03

### Added
- New release automation skill in git plugin

### Changed
- Updated plugin description to include release

## [1.5.0] - 2026-02-15

### Added
- Previous feature

[Unreleased]: https://github.com/user/repo/compare/v1.6.0...HEAD
[1.6.0]: https://github.com/user/repo/compare/v1.5.0...v1.6.0
[1.5.0]: https://github.com/user/repo/releases/tag/v1.5.0

Release Skill: Troubleshooting

Common Issues

"No CHANGELOG entry found for version X.Y.Z"

Cause: CHANGELOG.md doesn't have a ## [X.Y.Z] header.

Fix:

# Generate the entry
/changelog --version X.Y.Z

# Or manually add the header
echo "## [X.Y.Z] - $(date +%Y-%m-%d)" >> CHANGELOG.md

"Release vX.Y.Z already exists"

Cause: A GitHub Release with this tag already exists.

Fix:

# Delete the existing release
gh release delete vX.Y.Z --yes

# Optionally delete the tag too
git push origin --delete vX.Y.Z
git tag -d vX.Y.Z

# Retry
/release X.Y.Z

"Invalid version format"

Cause: Version doesn't match semantic versioning (X.Y.Z).

Valid formats:

• 1.6.0
• v1.6.0 (v prefix is stripped automatically)

Invalid formats:

• 1.6 (missing patch)
• 1.6.0-beta (pre-release suffixes not supported)
• v1.6 (missing patch even with prefix)

"Could not find workflow run"

Cause: The workflow didn't start within the 5-second wait period, or the workflow file doesn't exist.

Fix: 1. Check the workflow exists:

   gh workflow list

2. If missing, scaffold it:

   /release --setup

3. If it exists but didn't trigger, check permissions:

   gh api repos/{owner}/{repo}/actions/permissions

gh CLI Not Authenticated

Cause: gh CLI is not installed or not authenticated.

Fix:

# Install gh CLI
brew install gh    # macOS
# or see https://cli.github.com/

# Authenticate
gh auth login

"Could not find [Unreleased] link to update"

Cause: CHANGELOG.md doesn't have an [Unreleased]: link reference at the bottom.

Fix: Add the link reference manually:

[Unreleased]: https://github.com/user/repo/compare/vX.Y.Z...HEAD

Workflow Fails with "CHANGELOG entry not found"

Cause: The CHANGELOG.md was not pushed to the remote before the workflow ran.

Fix: Ensure Step 4 (commit and push) completed before the workflow triggers. Re-run:

git push origin main
/release X.Y.Z

Setup Files Already Exist

Cause: Running --setup when release infrastructure already exists.

Fix: The skill will warn about existing files. Choose to:

• Overwrite — Replace with latest templates
• Skip — Keep existing files unchanged

sed Errors on macOS vs Linux

Cause: sed -i behaves differently on macOS (BSD) and Linux (GNU).

Fix: The scripts use sed -i.bak which works on both platforms. The .bak files are cleaned up automatically with rm -f *.bak.

Debugging Tips

Check Workflow Status Manually

# List recent workflow runs
gh run list --workflow=release.yml --limit=5

# View specific run
gh run view <run-id>

# View logs
gh run view <run-id> --log

Verify CHANGELOG Format

# Check version headers
grep -E "^## \[" CHANGELOG.md

# Check link references
grep -E "^\[" CHANGELOG.md | tail -10

Test Release Script Locally

# Dry run (validate only, don't trigger)
# Check prerequisites
gh auth status
gh repo view --json url -q '.url'
grep -E "^## \[1.6.0\]" CHANGELOG.md
gh release view v1.6.0 2>/dev/null; echo "Exit: $?"

Release Workflow: Detailed Process

Overview

The release workflow operates in 7 phases for creating releases, plus a separate scaffolding workflow for setting up new projects.

Phase 1: Input Validation

Parse and validate all arguments before any side effects.

Arguments:

• <version> — Semantic version (e.g., 1.6.0 or v1.6.0)
• --yes / -y — Skip interactive confirmation (for CI/automation)
• --skip-monitor — Trigger workflow without waiting for completion
• --setup — Switch to scaffolding mode

Validation Rules:

• Version must match ^[0-9]+\.[0-9]+\.[0-9]+$ after stripping v prefix
• Version argument is required (unless --setup mode)

Phase 2: Pre-flight Checks

Verify all prerequisites before making changes.

1. CHANGELOG entry exists — grep -qE "^## \[$VERSION\]" CHANGELOG.md 2. Release doesn't exist — gh release view "v$VERSION" returns non-zero 3. gh CLI authenticated — gh auth status succeeds 4. Git remote accessible — gh repo view returns repo URL

If any check fails, report the issue and exit with clear instructions.

Phase 3: CHANGELOG Link Management

Add comparison links to the bottom of CHANGELOG.md.

Previous Version Detection

# Find the second ## [X.Y.Z] header (first is current version)
PREV_VERSION=$(grep -E "^## \[[0-9]+\.[0-9]+\.[0-9]+\]" CHANGELOG.md \
    | head -2 | tail -1 | sed 's/.*\[\([0-9.]*\)\].*/\1/')

Link Format

• With previous version: [1.6.0]: https://github.com/user/repo/compare/v1.5.0...v1.6.0
• First version: [1.0.0]: https://github.com/user/repo/releases/tag/v1.0.0

Idempotency

Skip if grep -qE "^\[$VERSION\]:" CHANGELOG.md already matches.

Unreleased Link Update

The [Unreleased] link is updated to compare from the new version to HEAD:

[Unreleased]: https://github.com/user/repo/compare/v1.6.0...HEAD

Phase 4: Git Operations

Commit and push CHANGELOG.md changes if modified.

1. Check for uncommitted changes: git diff --quiet CHANGELOG.md 2. Confirm with user before committing (unless --yes flag) 3. Stage: git add CHANGELOG.md 4. Commit: git commit -m "docs: prepare release $VERSION" 5. Push: git push origin main

Phase 5: Workflow Triggering

Trigger the GitHub Actions release workflow.

gh workflow run release.yml -f version="$VERSION"

The workflow must:

• Accept a version input via workflow_dispatch
• Have contents: write permission
• Use actions/checkout@v4 with fetch-depth: 0

Phase 6: Workflow Monitoring

Poll workflow status until completion (unless --skip-monitor).

1. Wait 5 seconds for workflow to register 2. Get run ID: gh run list --workflow=release.yml --limit=1 --json databaseId 3. Poll every 5 seconds: gh run view "$RUN_ID" --json status -q '.status' 4. On completion, check conclusion: gh run view "$RUN_ID" --json conclusion

Status Values

• queued — Waiting for runner
• in_progress — Running
• completed — Finished (check conclusion)

Conclusion Values

• success — Release created
• failure — Step failed
• cancelled — Manually cancelled

Phase 7: Post-Release

Report result with actionable URLs.

On success:

Release v1.6.0 created successfully!
View: https://github.com/user/repo/releases/tag/v1.6.0

On failure:

Workflow failed: failure
Logs: https://github.com/user/repo/actions/runs/12345

Setup Mode Workflow

When --setup is specified, scaffold the full release pipeline.

Step 1: Check Existing Files

Before scaffolding, check if any target files already exist:

• scripts/release.sh
• .github/workflows/release.yml
• .github/workflows/scripts/validate-changelog.sh
• .github/workflows/scripts/extract-release-notes.sh
• .github/workflows/scripts/create-github-release.sh

If files exist, warn the user and ask whether to overwrite.

Step 2: Create Directories

mkdir -p scripts
mkdir -p .github/workflows/scripts

Step 3: Copy Templates

Read each template from the skill's directories and write to target locations:

Step 4: Set Permissions

chmod +x scripts/release.sh
chmod +x .github/workflows/scripts/*.sh

Step 5: Report

List all created files and provide next steps: 1. Ensure CHANGELOG.md exists 2. Commit the scaffolded files 3. Run /release <version> for the first release

Script Templates Reference

release.sh

Local release orchestrator that wraps the full workflow. Supports --yes for non-interactive use and --skip-monitor to skip polling.

release.yml (GitHub Actions)

Workflow triggered by workflow_dispatch with a version input. Steps: 1. Checkout with full history 2. Validate semver format 3. Check release doesn't exist 4. Check/create git tag 5. Validate CHANGELOG entry 6. Extract release notes 7. Create GitHub Release

validate-changelog.sh

Verifies ## [VERSION] header exists in CHANGELOG.md. Uses Keep a Changelog format.

extract-release-notes.sh

Extracts content between ## [VERSION] and the next ## [ header using awk. Outputs to release_notes.md.

create-github-release.sh

Creates a GitHub Release via gh release create using the extracted release notes. Requires GH_TOKEN environment variable.

Integration with Other Skills

• `/changelog` (generating-changelog) — Generate CHANGELOG entries before releasing
• `/commit` (creating-commit) — Commit changes during release preparation
• `/create-pr` (creating-pr) — Create PRs if releasing from a branch