Creating Releases

GitHub Releases let you package and distribute versions of your software. They're built on Git tags and provide a user-friendly way to download specific versions.

What are Releases?

Releases are tagged snapshots of your project:

Repository
    │
    ├── v1.0.0 (Release)
    │   ├── Source code (zip/tar.gz)
    │   └── Compiled binaries
    │
    ├── v1.1.0 (Release)
    │   ├── Source code
    │   └── Compiled binaries
    │
    └── v2.0.0 (Pre-release)
        └── Source code (beta)

Tags vs Releases

Tags	Releases
Git feature	GitHub feature
Just a pointer to commit	Tag + additional info
Command line only	Web interface
No attached files	Can attach binaries
No release notes	Full release notes

Releases are built on top of tags.

Creating Tags

Lightweight Tag

# Simple pointer to commit
git tag v1.0.0
git push origin v1.0.0

Annotated Tag (Recommended)

# Tag with message, author, date
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0

Tag from Specific Commit

git tag -a v1.0.0 abc1234 -m "Release 1.0.0"

List Tags

git tag
git tag -l "v1.*"  # Pattern matching

Delete Tag

# Local
git tag -d v1.0.0

# Remote
git push origin --delete v1.0.0

Creating a Release

From Web UI

1. Go to repository
2. Click "Releases" (right sidebar)
3. Click "Create a new release"
4. Choose or create tag
5. Fill in details
6. Attach files
7. Publish

From GitHub CLI

# Create release from existing tag
gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes here"

# Create tag and release together
gh release create v1.0.0 --generate-notes

# Upload assets
gh release create v1.0.0 dist/app.zip dist/app.tar.gz

# Create draft release
gh release create v1.0.0 --draft

# Create pre-release
gh release create v1.0.0-beta --prerelease

Release Components

Tag

Version identifier (e.g., v1.0.0).

Title

Human-readable name (e.g., "Version 1.0.0 - New Dashboard").

Description

Release notes in Markdown:

## What's New

### Features
- Added dark mode (#123)
- New dashboard widget (#456)

### Bug Fixes
- Fixed login timeout (#789)
- Resolved memory leak (#101)

### Breaking Changes
- API v1 deprecated (use v2)

## Upgrade Guide

1. Update dependencies
2. Run migrations
3. Clear cache

## Contributors

Thanks to @user1, @user2 for their contributions!

Assets

Attach downloadable files:

• Compiled binaries
• Installers
• Documentation
• Checksums

Pre-release Flag

Mark as pre-release (beta, alpha, RC):

• Shows warning to users
• Doesn't show as "latest"

Latest Release

Most recent non-pre-release is marked "Latest".

Auto-Generated Release Notes

GitHub can generate notes from merged PRs:

Using Web UI

Click "Generate release notes" button.

Using CLI

gh release create v1.0.0 --generate-notes

Configuration

Create .github/release.yml:

changelog:
  exclude:
    labels:
      - skip-changelog
  categories:
    - title: Features
      labels:
        - feature
        - enhancement
    - title: Bug Fixes
      labels:
        - bug
        - bugfix
    - title: Documentation
      labels:
        - documentation
    - title: Other Changes
      labels:
        - "*"

Semantic Versioning

Use semantic versioning (SemVer):

MAJOR.MINOR.PATCH

v1.0.0 → v1.0.1 (patch: bug fixes)
v1.0.1 → v1.1.0 (minor: new features, backwards compatible)
v1.1.0 → v2.0.0 (major: breaking changes)

Pre-release versions:

v2.0.0-alpha.1
v2.0.0-beta.1
v2.0.0-rc.1
v2.0.0

Automated Releases

GitHub Actions

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: npm run build

      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            dist/*.zip
            dist/*.tar.gz
          generate_release_notes: true

Continuous Delivery

name: Release on Merge

on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get next version
        id: version
        run: echo "version=$(./scripts/next-version.sh)" >> $GITHUB_OUTPUT

      - name: Create tag
        run: |
          git tag v${{ steps.version.outputs.version }}
          git push origin v${{ steps.version.outputs.version }}

      - name: Create release
        uses: softprops/action-gh-release@v1
        with:
          tag_name: v${{ steps.version.outputs.version }}
          generate_release_notes: true

Downloading Releases

From Web UI

1. Go to Releases page
2. Find version
3. Download source or assets

From CLI

# List releases
gh release list

# Download assets
gh release download v1.0.0

# Download specific asset
gh release download v1.0.0 --pattern "*.zip"

Direct URLs

# Source code
https://github.com/owner/repo/archive/refs/tags/v1.0.0.zip

# Specific asset
https://github.com/owner/repo/releases/download/v1.0.0/app.zip

# Latest release
https://github.com/owner/repo/releases/latest

Release Best Practices

Consistent Versioning

Use semantic versioning consistently.

Meaningful Release Notes

• List all changes
• Highlight breaking changes
• Include upgrade instructions
• Thank contributors

Test Before Release

Run full test suite on the tagged commit.

Sign Releases

For security-sensitive projects:

• GPG-signed tags
• Checksums for assets

Keep Changelog

Maintain a CHANGELOG.md:

# Changelog

## [1.1.0] - 2025-01-15

### Added
- New feature X

### Fixed
- Bug in Y

## [1.0.0] - 2025-01-01

Initial release.

Summary

• Releases are GitHub's way to distribute versioned software
• Built on Git tags with additional features
• Include release notes, assets, and metadata
• Use semantic versioning (MAJOR.MINOR.PATCH)
• Auto-generate notes from PRs
• Automate releases with GitHub Actions
• Mark pre-releases appropriately

In the next module, we'll cover Git best practices.