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
- Go to repository
- Click "Releases" (right sidebar)
- Click "Create a new release"
- Choose or create tag
- Fill in details
- Attach files
- 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
- Go to Releases page
- Find version
- 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.
التالي · الدرس 37 من 40
Writing Good Commit Messages
قراءة 4 دقيقة
أنهيت 36 من 40 درسًا

اسأل Byte عن هذا الدرس
محادثة خاصة حول هذا الدرس. قرأ Byte الدرس كاملًا، ويجيب خلال ثوانٍ، ويُظهر القسم الذي تأتي منه كل إجابة. يمكنك السؤال بأي لغة.
الأسئلة والأجوبة
أسئلة عامة حول هذا الدرس. يجيب AI Tutor فورًا بلغتك، ويراجع فريق FreeAcademy الإجابات، ويمكن لكل المتعلمين قراءتها.

