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

Expected: A version number is chosen that accurately reflects the scope of changes since the last release.

On failure: If unsure whether changes are breaking, review the public API diff. Any removal or signature change of an exported function is a breaking change requiring a MAJOR bump.

Step 2: Update Version in Project Files

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

Expected: The version number is updated in the appropriate project file and committed to version control.

On failure: If the version was already updated in a previous step (e.g., via usethis::use_version() in R), verify it matches the intended release version.

Step 3: Write Release Notes

Create or update changelog. Organize by category:

## 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

Expected: Release notes are organized by category (features, fixes, breaking changes) with issue/PR references for traceability.

On failure: If changes are hard to categorize, review git log v1.0.0..HEAD --oneline to reconstruct the list of changes since the last release.

Step 4: Create Git Tag

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

Expected: An annotated tag v1.1.0 exists locally and on the remote. git tag -l shows the tag.

On failure: If the tag already exists, delete it with git tag -d v1.1.0 && git push origin :refs/tags/v1.1.0 and recreate it. If push is rejected, ensure you have write access to the remote.

Step 5: Create GitHub Release

Using GitHub CLI (recommended):

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

With artifacts:

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:

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 attached artifacts (if any).

On failure: If gh is not authenticated, run gh auth login. If the tag does not exist on the remote, push it first with git push origin v1.1.0.

Step 6: Auto-Generate Release Notes

GitHub can auto-generate notes from merged PRs:

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

Configure categories in .github/release.yml:

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

Expected: Release notes are auto-generated from merged PR titles, categorized by label. .github/release.yml controls the categories.

On failure: If auto-generated notes are empty, ensure PRs were merged (not closed) and had labels assigned. Manually write notes as a fallback.

Step 7: Verify Release

# List releases
gh release list

# View specific release
gh release view v1.1.0

Expected: gh release list shows the new release. gh release view displays the correct title, tag, notes, and assets.

On failure: If the release is missing, check the Actions tab for any release workflows that may have failed. Verify the tag exists with git tag -l.

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

create-github-release