Release Automation
Semantic versioning, conventional commits, auto-generated changelogs, and GitHub Releases — ship with confidence
Skills taught: cicd.semver, cicd.conventional-commits, cicd.changelog, cicd.github-releases, cicd.npm-publish
Semantic versioning — a shared contract
Semantic versioning (SemVer) defines version numbers as MAJOR.MINOR.PATCH. The rules are simple and universally understood: increment PATCH for bug fixes that don't break anything, MINOR for new features that are backward-compatible, MAJOR for breaking changes. When a user sees v2.0.0, they know to read the migration guide. When they see v1.2.3, they can upgrade safely.
- Conventional Commits
- A commit message standard that encodes the type and scope of each change. Format: <code>type(scope): description</code>. Examples: <code>feat: add dark mode</code>, <code>fix(auth): token expiry off by one</code>, <code>feat!: redesign API (BREAKING CHANGE)</code>. When commits follow this standard, tools can automatically determine the next version number and generate a changelog.
Automated release with release-please
name: Release
on:
push:
branches: [main]
permissions:
contents: write
pull-requests: write
jobs:
release-please:
runs-on: ubuntu-latest
steps:
- uses: google-github-actions/release-please-action@v4
id: release
with:
release-type: node # or: python, go, rust, simple
token: ${{ secrets.GITHUB_TOKEN }}
# The action:
# 1. Reads all conventional commits since the last release
# 2. Determines the next version (feat→minor, fix→patch, BREAKING→major)
# 3. Opens a 'Release PR' with bumped version + auto-generated CHANGELOG.md
# 4. When you MERGE the Release PR → creates a git tag + GitHub Release
# Build and publish after release merges:
- uses: actions/checkout@v4
if: ${{ steps.release.outputs.release_created }}
- uses: actions/setup-node@v4
if: ${{ steps.release.outputs.release_created }}
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- run: npm ci
if: ${{ steps.release.outputs.release_created }}
- name: Publish to npm
if: ${{ steps.release.outputs.release_created }}
run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
Manual GitHub Release with built artifacts
name: Release
on:
push:
tags:
- 'v*' # triggers on: git tag v1.2.3 && git push --tags
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20', cache: 'npm' }
- run: npm ci
- run: npm test
- name: Build
run: npm run build
# Create a .zip of the build artifacts
- name: Package
run: zip -r release-${{ github.ref_name }}.zip dist/
# Create GitHub Release with the zip attached
- name: Create Release
uses: softprops/action-gh-release@v2
with:
name: Release ${{ github.ref_name }}
# Auto-generate release notes from commits since last tag
generate_release_notes: true
files: |
release-${{ github.ref_name }}.zip
dist/CHANGELOG.md
# If the tag is a prerelease (v1.0.0-beta.1), mark it
prerelease: ${{ contains(github.ref_name, '-') }}
Conventional commit types and their impact
# PATCH bump (1.0.x → 1.0.x+1):
git commit -m "fix: handle null response from API"
git commit -m "fix(auth): token not refreshed before expiry"
git commit -m "perf: lazy-load dashboard charts"
# MINOR bump (1.x.0 → 1.x+1.0):
git commit -m "feat: add CSV export to reports page"
git commit -m "feat(notifications): email digest settings"
# MAJOR bump (x.0.0 → x+1.0.0):
git commit -m "feat!: redesign authentication API"
# OR in the commit body:
git commit -m "feat: new auth system" -m "BREAKING CHANGE: token format changed, existing tokens invalid"
# No version bump (docs, tests, CI, style, refactor):
git commit -m "docs: update README installation steps"
git commit -m "test: add edge cases for date parser"
git commit -m "chore: upgrade devDependencies"
git commit -m "ci: add docker build cache"
Tip: The Release PR is your review gate. release-please opens a PR that shows the auto-generated CHANGELOG and the proposed new version number. You review it: is v2.0.0 really justified? Did a commit accidentally trigger a MAJOR bump when it shouldn't have? You can edit the PR, then merge it to trigger the release. This human checkpoint prevents accidental major version bumps.
Frequently Asked Questions
We don't publish to npm. Is release automation still worth it?
Yes — for any project. GitHub Releases give you a versioned artifact download page, auto-generated release notes, and a clear history of what shipped when. For internal apps or services, the release tag becomes the deployment identifier: 'we're running v2.3.1 in production' is far clearer than referencing a commit SHA. The changelog also builds automatically — zero overhead for the team.