Create GitHub Release

Create a tagged GitHub release with release notes and optional artifacts.

When to Use

•Marking a stable version of software for distribution
•Publishing a new version of a library or application
•Creating release notes for stakeholders
•Distributing build artifacts (binaries, tarballs)

Inputs

•Required: Version number (semantic versioning)
•Required: Summary of changes since last release
•Optional: Build artifacts to attach
•Optional: Whether this is a pre-release

Procedure

Step 1: Determine Version Number

Follow semantic versioning (MAJOR.MINOR.PATCH):

Change	Example	When
MAJOR	1.0.0 -> 2.0.0	Breaking changes
MINOR	1.0.0 -> 1.1.0	New features, backward compatible
PATCH	1.0.0 -> 1.0.1	Bug fixes only

Step 2: Update Version in Project Files

•DESCRIPTION (R packages)
•package.json (Node.js)
•Cargo.toml (Rust)
•pyproject.toml (Python)

Step 3: Write Release Notes

Create or update changelog. Organize by category:

markdown

## What's Changed

### New Features
- Added user authentication (#42)
- Support for custom themes (#45)

### Bug Fixes
- Fixed crash on empty input (#38)
- Corrected date parsing in UTC (#41)

### Improvements
- Improved error messages
- Updated dependencies

### Breaking Changes
- `old_function()` renamed to `new_function()` (#50)

**Full Changelog**: https://github.com/user/repo/compare/v1.0.0...v1.1.0

Step 4: Create Git Tag

bash

git tag -a v1.1.0 -m "Release v1.1.0"
git push origin v1.1.0

Step 5: Create GitHub Release

Using GitHub CLI (recommended):

bash

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes-file CHANGELOG.md

With artifacts:

bash

gh release create v1.1.0 \
  --title "v1.1.0" \
  --notes "Release notes here" \
  build/app-v1.1.0.tar.gz \
  build/app-v1.1.0.zip

Pre-release:

bash

gh release create v2.0.0-beta.1 \
  --title "v2.0.0 Beta 1" \
  --prerelease \
  --notes "Beta release for testing"

Expected: Release visible on GitHub with tag, notes, and artifacts.

Step 6: Auto-Generate Release Notes

GitHub can auto-generate notes from merged PRs:

bash

gh release create v1.1.0 \
  --title "v1.1.0" \
  --generate-notes

Configure categories in .github/release.yml:

yaml

changelog:
  categories:
    - title: New Features
      labels:
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
    - title: Documentation
      labels:
        - documentation
    - title: Other Changes
      labels:
        - "*"

Step 7: Verify Release

bash

# List releases
gh release list

# View specific release
gh release view v1.1.0

Validation

• Version tag follows semantic versioning
• Git tag points to the correct commit
• Release notes accurately describe changes
• Artifacts (if any) are attached and downloadable
• Release is visible on the GitHub repository page
• Pre-release flag is set correctly

Common Pitfalls

•Tagging wrong commit: Always verify git log before tagging. Tag after version-bump commit.
•Forgetting to push tags: git push doesn't push tags. Use git push --tags or git push origin v1.1.0.
•Inconsistent version format: Decide on v1.0.0 vs 1.0.0 and stick with it.
•Empty release notes: Always provide meaningful notes. Users need to know what changed.
•Deleting and recreating tags: Avoid changing tags after push. If needed, create a new version instead.

Related Skills

•commit-changes - staging and committing workflow
•manage-git-branches - branch management for release prep
•release-package-version - R-specific release workflow
•configure-git-repository - Git setup prerequisite
•setup-github-actions-ci - automate releases via CI