GitHub Release Creation Skill

This skill helps you create professional, comprehensive GitHub releases using the gh CLI tool. It covers release notes drafting, version management, and best practices for open-source release communication.

When to Use This Skill

Trigger this skill when you encounter requests like:

• "Create a GitHub release for version X.Y.Z"
• "Help me draft release notes"
• "Publish a release with these changes"
• "Compare version A.B.C and version X.Y.Z"
• "Make a release for this project"

Prerequisites

1. GitHub CLI (gh) must be installed and authenticated

``bash gh auth status ` Should show: ✓ Logged in to github.com account <username>`

1. Git repository should be properly tagged

``bash git tag -l "v*" ``

Core Concepts

Version Numbering (Semantic Versioning)

• Major (X.0.0): Breaking changes, major features
• Minor (x.Y.0): New features, backward compatible
• Patch (x.y.Z): Bug fixes, small improvements

Release Types

• Stable Release: Final production-ready version (e.g., v4.0.0)
• Pre-release: Alpha, beta, or RC versions (e.g., v4.0.0-rc.1)
• Draft Release: Work-in-progress release notes

Step-by-Step Release Creation Process

Step 1: Analyze Changes Since Last Release

Identify the base version to compare against:

# Get latest tags
git tag -l "v*" --sort=-version:refname | head -5

# Get commits since last release
git log v3.3.0..HEAD --oneline

# Get detailed commit messages
git log v3.3.0..HEAD --pretty=format:"%h|%ad|%s" --date=short

Key information to extract:

• Commit count since last release
• Major features added
• Bug fixes and improvements
• Breaking changes (if any)
• Performance improvements
• Documentation updates

Step 2: Determine Version Number

Guidelines for choosing version numbers:

Questions to ask:

• Does this introduce breaking changes? → Major bump
• Are there significant new features? → Minor bump
• Is it primarily bug fixes? → Patch bump

Step 3: Draft Release Notes

Structure professional release notes with these sections:

1. Overview (2-3 sentences)

• High-level summary of the release
• Key theme or focus area
• Version significance (major/minor/patch)

2. What's New (categorized changes)

Organize changes by type:

• ✨ Features: New functionality
• 🔧 Performance: Speed/resource improvements
• 🐛 Bug Fixes: Resolved issues
• 📚 Documentation: Doc updates
• 💥 Breaking Changes: Incompatible changes (if any)
• ♻️ Refactoring: Code quality improvements

3. Comparison with Previous Version

Create comparison tables showing behavior changes:

• Before (vX.Y.Z) → After (vX.Y.Z)
• Performance metrics
• Feature additions
• Configuration changes

4. Migration Guide (if applicable)

• Configuration changes needed
• Breaking changes and how to adapt
• Deprecated features
• Upgrade steps

5. Installation Instructions

# Docker
docker pull user/repo:version

# Build from source
git clone https://github.com/user/repo.git
cd repo
git checkout vX.Y.Z
go build -o binary ./cmd/

# Download binaries
# Link to release assets

6. Full Changelog

List all commits with hashes and dates:

### Commits since v3.3.0

- `9a8ebda` - Fix: Bypass internal HTTP proxy server (2026-01-09)
- `680f785` - Feat: Add SOCKS5 Direct Mode (2025-12-15)

7. Additional Sections (as needed)

• Known Issues
• Credits/Contributors
• License information
• Related links

Step 4: Create Git Tag

# Create annotated tag
git tag -a v4.0.0 -m "Release v4.0.0: Major performance improvements"

# Or create lightweight tag
git tag v4.0.0

# Push tag to GitHub
git push origin v4.0.0

# Or push all tags
git push origin --tags

Step 5: Create GitHub Release Using gh CLI

Basic Release Creation

gh release create v4.0.0 \
  --title "v4.0.0 - Major Performance Release" \
  --notes "Release notes here..."

Advanced Options

# Create release from notes file
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes-file RELEASE_NOTES.md

# Create draft release (not published yet)
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Draft notes" \
  --draft

# Create pre-release
gh release create v4.0.0-beta.1 \
  --title "v4.0.0-beta.1" \
  --notes "Beta release notes" \
  --prerelease

# Release with target commit
gh release create v4.0.0 \
  --target main \
  --title "v4.0.0" \
  --notes "Release notes"

# Release from existing tag notes
gh release create v4.0.0 \
  --notes-tag \
  --title "v4.0.0"

Release with Assets

# Attach binaries
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Release notes" \
  ./dist/binary-linux-amd64 \
  ./dist/binary-darwin-amd64 \
  ./dist/binary-windows-amd64.exe

# Attach all files from directory
gh release create v4.0.0 \
  --title "v4.0.0" \
  --notes "Release notes" \
  ./dist/*

Step 6: Publish and Verify

# View release
gh release view v4.0.0

# List all releases
gh release list

# Open in browser
gh browse --release v4.0.0

# Edit if needed
gh release edit v4.0.0 --notes "Updated notes"

Release Notes Template

````markdown

[Project Name] v[VERSION]

🎉 Overview

[2-3 sentence summary of the release]

🚀 What's New

✨ Features

• Feature name: Description of the feature

- Technical details - Benefits for users

🔧 Performance Improvements

🐛 Bug Fixes

• Fixed issue where [description]
• Resolved [problem] by [solution]

📚 Documentation

• Updated [file] with [information]
• Added guide for [topic]

📊 Comparison with v[PREVIOUS_VERSION]

Behavior Changes

Technical Details

• Architecture: [description of changes]
• Modified Files:

- [file1](link) - Change description - [file2](link) - Change description

🔄 Migration from v[PREVIOUS]

✅ No Configuration Changes Required

[If applicable: "This release is 100% backward compatible"]

Breaking Changes

[If any: List breaking changes and migration steps]

🛠️ Installation

Docker

docker pull user/repo:v[VERSION]

````

Build from Source

git clone https://github.com/user/repo.git
cd repo
git checkout v[VERSION]
[build commands]

Download Binaries

Download from Releases page.

📋 Full Changelog

Commits since v[PREVIOUS]

• hash - Type: Description (date)
• hash - Type: Description (date)

🐛 Known Issues

[List any known issues or "None reported"]

🙏 Credits

Contributors:

• @username1
• @username2

📄 License

[License information]

🔗 Links

• [Documentation](link)
• [Migration Guide](link)
• [GitHub Repository](link)

Full Changelog: https://github.com/user/repo/compare/v[PREVIOUS]...v[CURRENT]

````

Best Practices

DO ✅

1. Use semantic versioning consistently
2. Write comprehensive release notes that stand alone
3. Include installation instructions for common use cases
4. Highlight breaking changes prominently
5. Credit contributors who helped with the release
6. Link to related issues/PRs when relevant
7. Use consistent formatting (Markdown tables, code blocks)
8. Test the release process on a test repository first
9. Keep release notes concise but complete
10. Include comparison data for performance changes

DON'T ❌

1. NEVER create releases without proper tagging
2. NEVER skip authentication check before creating releases
3. NEVER publish release notes without review
4. DON'T use internal jargon without explanation
5. DON'T forget to verify the release after creation
6. DON'T create major releases for trivial changes
7. DON'T skip backward compatibility notes for breaking changes
8. DON'T forget to push tags to remote repository
9. DON'T use vague commit messages (improves changelog quality)
10. NEVER release untested code to production

Common Workflows

Workflow 1: Regular Feature Release

# 1. Checkout main branch
git checkout main
git pull

# 2. Review changes since last release
git tag -l "v*" --sort=-version:refname | head -1
git log v3.3.0..HEAD --oneline

# 3. Determine version (e.g., v3.4.0 for new features)

# 4. Create tag
git tag -a v3.4.0 -m "Release v3.4.0: New features and improvements"
git push origin v3.4.0

# 5. Create release (from prepared notes file)
gh release create v3.4.0 \
  --title "v3.4.0 - New Features" \
  --notes-file RELEASE_NOTES.md
````

### Workflow 2: Hotfix Patch Release

1. Create hotfix branch

git checkout -b hotfix/critical-bug-fix

2. Make fix and commit

git commit -m "fix: Critical security vulnerability"

3. Create patch tag

git tag -a v3.3.1 -m "Release v3.3.1: Critical security fix" git push origin hotfix/critical-bug-fix v3.3.1

4. Create release with urgent notes

gh release create v3.3.1 \ --title "v3.3.1 - Security Fix" \ --notes "## 🚨 Security Fix

This release addresses a critical security vulnerability.

Upgrade immediately if you are affected.

[Fix details]"

### Workflow 3: Major Version Release

1. Comprehensive changelog analysis

git log v3.0.0..HEAD --pretty=format:"%h|%ad|%s" --date=short > changes.txt

2. Create migration guide

Write MIGRATION.md with breaking changes

3. Create major tag

git tag -a v4.0.0 -m "Release v4.0.0: Major architecture improvements" git push origin v4.0.0

4. Create comprehensive release

gh release create v4.0.0 \ --title "v4.0.0 - Major Release" \ --notes-file COMPREHENSIVE_NOTES.md \ --draft

5. Review and publish

gh release view v4.0.0 --web

(Review in browser, then publish when ready)

### Workflow 4: Pre-release (Beta/RC)

1. Create pre-release tag

git tag -a v4.0.0-beta.1 -m "Beta 1 for v4.0.0" git push origin v4.0.0-beta.1

2. Create pre-release

gh release create v4.0.0-beta.1 \ --title "v4.0.0-beta.1 - Testing Release" \ --notes "## 🧪 Beta Release

This is a pre-release for testing purposes.

Not recommended for production use.

[Features to test]" \ --prerelease

3. After testing, create final release

git tag -a v4.0.0 -m "Release v4.0.0" git push origin v4.0.0 gh release create v4.0.0 --notes "Final release notes"

## Troubleshooting

### Issue: "gh not authenticated"

**Solution:**

gh auth login gh auth status # Verify

### Issue: "Tag not found"

**Solution:**

Push tag first

git push origin <tag-name>

Or verify tag exists

git tag -l | grep <tag-name>

### Issue: "Release already exists"

**Solution:**

Delete existing release

gh release delete <tag-name> --yes

Or edit existing release

gh release edit <tag-name> --notes "New notes"

### Issue: "Permission denied"

**Solution:**

- Verify repository permissions: `gh repo view`
- Check authentication: `gh auth status`
- Ensure you have admin/write access

## Additional Resources

- [GitHub Releases Documentation](https://docs.github.com/en/repositories/releasing-projects-on-github)
- [GitHub CLI Manual](https://cli.github.com/manual/)
- [Semantic Versioning](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)

## Tips for High-Quality Releases

1. **Start Early**: Begin drafting release notes during development
2. **Track Features**: Maintain a CHANGELOG.md file
3. **Communicate**: Use issues/PRs to discuss release plans
4. **Test Thoroughly**: Test installation instructions
5. **Be Honest**: Clearly document known issues
6. **Celebrate**: Highlight community contributions
7. **Stay Organized**: Use consistent structure across releases
8. **Provide Context**: Explain why changes matter to users
9. **Include Metrics**: Use data to demonstrate improvements
10. **Link Forward**: Point to next version or roadmap

## Example Commands Reference

View all gh release commands

gh release --help

Create release from stdin

echo "Release notes" | gh release create v1.0.0

Create release with discussion

gh release create v1.0.0 \ --discussion "Discuss v1.0.0 release"

Delete release

gh release delete v1.0.0 --yes

Download release assets

gh release download v1.0.0 \ --dir ./downloads \ --pattern "*.zip"

List releases

gh release list \ --limit 20 \ --json name,tagName,publishedAt

---

**Remember**: Good releases communicate value, build trust, and make users
excited about your project!