| name | release |
| description | Create a GitHub release and prepare changelog notes for a version tag. Use when the user wants to publish or draft a repository release, not merely create a Git commit, tag, or pull request. |
Create GitHub Release
Create a release using the GitHub CLI (gh) with auto-generated or custom changelog notes.
Arguments
$ARGUMENTS
Format: <version> [--draft] [--prerelease] [--target <branch>]
version - Version tag (e.g., v1.2.0, 1.2.0)--draft - Create as draft release--prerelease - Mark as pre-release--target - Target branch or commit (defaults to the repository's configured
default branch)
Examples
/github:release v1.2.0
/github:release v2.0.0-beta.1 --prerelease
/github:release v1.3.0 --draft
/github:release v1.4.0 --target main
Instructions
Required GitHub CLI preflight
Before any workflow step, read ../../references/github-cli-preflight.md and complete it. Do not run workflow commands until gh installation and authentication are verified.
-
Verify prerequisites: The required GitHub CLI preflight has already
confirmed installation, authentication, active identity, and repository.
Fetching tags changes local refs, so explain that and run it only as part of
an explicitly requested release workflow:
git fetch --tags
-
Validate and resolve the release target:
- Validate the version as a Git tag with
git check-ref-format "refs/tags/<version>".
- If
--target was supplied, resolve it to an exact commit SHA.
- Otherwise resolve the repository default branch, then its exact commit SHA.
-
Check if tag already exists:
git tag -l "$version"
gh release view "$version" 2>/dev/null
-
Find previous release tag, excluding the version being created:
git describe --tags --abbrev=0 --exclude "$version" 2>/dev/null ||
echo "No previous tag"
-
Generate changelog against the resolved target commit:
git log <previous_tag>..<target_sha> --pretty=format:"%h %s" --no-merges
-
Categorize changes into sections:
- Features -
feat: commits
- Bug Fixes -
fix: commits
- Performance -
perf: commits
- Breaking Changes - commits with
BREAKING CHANGE: or !:
- Documentation -
docs: commits
- Other Changes - remaining commits
-
Prepare safe content: Create the release title and notes as separate
temporary files. Do not interpolate either into a shell command.
-
Require final confirmation: Show the verified repository, version,
exact target commit SHA, title, draft/prerelease state, and a notes summary.
Do not create the release until the user explicitly confirms.
-
Create the release: Read the title from its file into a quoted variable
and always pass the exact target SHA:
release_title=$(<"$title_file")
gh release create "$version" \
--title "$release_title" \
--notes-file <changelog_file> \
--target <target_sha> \
[--draft] \
[--prerelease]
-
Report the release URL to the user.
Changelog Template
## What's Changed
### Features
- feat: description (#PR)
- feat(scope): description (#PR)
### Bug Fixes
- fix: description (#PR)
### Performance
- perf: description (#PR)
### Breaking Changes
- **BREAKING:** description
### Other Changes
- chore: description
- refactor: description
**Full Changelog**: https://github.com/owner/repo/compare/v1.1.0...v1.2.0
Smart Changelog Generation
When generating the changelog:
- Parse commit messages for conventional commit prefixes
- Extract PR numbers from commit messages or merge commits
- Link contributors using
@username when available
- Include comparison link at the bottom
- Highlight breaking changes prominently at the top if any exist
Error Handling
- If the GitHub CLI preflight fails, stop and follow its installation or
browser-authentication guidance; do not create a release.
- If tag exists: "Error: Release already exists. Use a different version."
- If no commits since last release: "Warning: No new commits since <previous_tag>"
Important
- Do NOT add any AI/LLM attribution
- Follow semantic versioning conventions
- Include breaking changes prominently if present
- Keep changelog entries concise but descriptive
