---

name: create-github-release locale: caveman-ultra source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Create a GitHub release with proper tagging, release notes, and optional build artifacts. Covers semantic versioning, changelog generation, and GitHub CLI usage. Use when marking a stable version of software for distribution, publishing a new library or application version, creating release notes for stakeholders, or distributing build artifacts (binaries, tarballs). license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: git complexity: basic language: multi tags: github, release, git-tags, changelog, versioning

Create GitHub Release

Tag + notes + artifacts → GitHub release.

Use When

• Mark stable ver for distrib
• Publish lib/app ver
• Release notes for stakeholders
• Distrib artifacts (bins, tarballs)

In

• Required: Ver # (semver)
• Required: Changes summary
• Optional: Build artifacts
• Optional: Pre-release flag

Do

Step 1: Ver

Semver (MAJOR.MINOR.PATCH):

Change	Example	When
MAJOR	1.0.0 -> 2.0.0	Breaking
MINOR	1.0.0 -> 1.1.0	New feat, backward compat
PATCH	1.0.0 -> 1.0.1	Bug fix only

Got: Ver matches change scope.

If err: Doubt breaking → review public API diff. Any removal / signature change of exported fn → breaking → MAJOR.

Step 2: Ver in Project Files

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

Got: Ver updated + committed.

If err: Already updated (usethis::use_version()) → verify match.

Step 3: Notes

Changelog by cat:

## 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: Notes by cat (feat/fix/breaking) + issue/PR refs.

If err: Hard to categorize → git log v1.0.0..HEAD --oneline → reconstruct.

Step 4: Tag

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

Got: Tag local + remote. git tag -l shows.

If err: Tag exists → git tag -d v1.1.0 && git push origin :refs/tags/v1.1.0 + recreate. Push rejected → check write access.

Step 5: Release

gh CLI (rec):

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

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 on GitHub w/ tag + notes + artifacts.

If err: gh not auth → gh auth login. Tag not on remote → git push origin v1.1.0.

Step 6: Auto-Gen Notes

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

Cats 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: Notes from merged PR titles by label. .github/release.yml → cats.

If err: Empty notes → PRs merged (not closed) + labels. Manual fallback.

Step 7: Verify

# List releases
gh release list

# View specific release
gh release view v1.1.0

Got: List shows. View shows correct title/tag/notes/assets.

If err: Missing → check Actions workflows. Verify tag: git tag -l.

Check

• Ver tag = semver
• Tag = correct commit
• Notes accurate
• Artifacts attached + downloadable
• Release visible on repo page
• Pre-release flag correct

Traps

• Wrong commit tag: Verify git log pre-tag. Tag after ver-bump commit.
• No push tags: git push doesn't. Use git push --tags / git push origin v1.1.0.
• Ver fmt inconsist: v1.0.0 vs 1.0.0 → pick + stick.
• Empty notes: Always meaningful. Users need "what changed".
• Delete+recreate tags: Avoid. Create new ver instead.

→

• commit-changes — stage + commit
• manage-git-branches — branch mgmt for release prep
• release-package-version — R-specific
• configure-git-repository — git setup
• setup-github-actions-ci — auto releases via CI