Create GitHub Release

Create tagged GitHub release with release notes and optional artifacts.

When Use

• Marking stable software version for distribution
• Publishing new version of library or app
• 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

Steps

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

Got: Version number chosen reflects scope of changes since last release.

If fail: Unsure if changes are breaking? Review public API diff. Any removal or signature change of exported function → breaking change needing MAJOR bump.

Step 2: Update Version in Project Files

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

Got: Version number updated in right project file and committed to version control.

If fail: Version already updated in earlier step (e.g., via usethis::use_version() in R)? Verify matches 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

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

If fail: Changes hard to categorize? Review git log v1.0.0..HEAD --oneline to rebuild list of changes since last release.

Step 4: Create Git Tag

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

Got: Annotated tag v1.1.0 exists locally and on remote. git tag -l shows tag.

If fail: Tag already exists? Delete with git tag -d v1.1.0 && git push origin :refs/tags/v1.1.0 and recreate. Push rejected? Confirm write access to 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"

Got: Release visible on GitHub with tag, notes, attached artifacts (if any).

If fail: gh not authenticated? Run gh auth login. Tag does not exist on 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:
        - "*"

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

If fail: Auto-generated notes empty? Confirm PRs were merged (not closed) and had labels. Write notes by hand as fallback.

Step 7: Verify Release

# List releases
gh release list

# View specific release
gh release view v1.1.0

Got: gh release list shows new release. gh release view displays right title, tag, notes, assets.

If fail: Release missing? Check Actions tab for release workflows that may have failed. Verify tag exists with git tag -l.

Checks

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

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: Pick v1.0.0 vs 1.0.0 and stick with it.
• Empty release notes: Always give meaningful notes. Users need to know what changed.
• Deleting and recreating tags: Dodge changing tags after push. If needed, create new version instead.

See Also

• 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