Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Pages, Packages and Releases

Releases, Tags and Semantic Versioning

Ship versions with GitHub Releases: Git tags, semantic versioning, release notes and automatically generated changelogs, assets and pre-releases, with a version-bump calculator.

A release is how a project says "this snapshot is a version you can use". On GitHub it is a page that combines a Git tag, human-readable notes and downloadable files. Users, package managers and your own deploy workflows can all rely on it. To use releases well you need three ideas: tags, a versioning scheme, and release notes.

Tags: names for commits

A Git tag is a permanent label on one commit. Branches move as you commit; tags stay put. There are two kinds:

  • Lightweight tags are just a name pointing at a commit.
  • Annotated tags store a message, the tagger and a date (and can be signed). Use these for releases.
Terminal
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0
git tag --list "v1.*"
git show v1.4.0

Tags are not pushed by git push alone; you push them by name, or all at once with git push --tags. To delete a mistaken tag: git tag -d v1.4.0 and git push origin :refs/tags/v1.4.0. If you want to review how tags relate to commits, the Git tutorial explains the object model.

Semantic versioning

Semantic Versioning (SemVer) gives the three numbers in MAJOR.MINOR.PATCH a meaning:

Bump When Example
MAJOR You make an incompatible change 1.4.2 -> 2.0.0
MINOR You add functionality in a backwards-compatible way 1.4.2 -> 1.5.0
PATCH You make a backwards-compatible bug fix 1.4.2 -> 1.4.3

Resetting rules: raising MINOR sets PATCH to 0; raising MAJOR sets both to 0. Versions below 1.0.0 mean "initial development, anything may change". Pre-release versions add a suffix (2.0.0-beta.1) and sort before the final release. Build metadata (+20260115) is ignored in ordering. Tag names conventionally add a v prefix (v2.0.0).

Many teams derive the bump from commit messages using Conventional Commits: a prefix like fix:, feat: or feat!: (or a BREAKING CHANGE: footer). fix means a patch, feat a minor, and a breaking marker a major. The calculator below applies those rules. It is a learning stand-in, simpler than real tools such as release-please or semantic-release.

JS Stand-in: next version from commit messages (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try changing the messages: a single breaking marker overrides everything else, and a batch of chore: and docs: commits needs no release at all.

Creating a release on GitHub

On the repository page click Releases -> Draft a new release (or Create a new release). Then:

  1. Pick an existing tag, or type a new one and choose the target branch or commit; GitHub creates the tag when you publish.
  2. Write a title and notes, or press Generate release notes.
  3. Attach assets (zip files, installers, checksums). GitHub automatically adds source code archives (.zip and .tar.gz) for the tag.
  4. Choose Set as a pre-release for betas and release candidates, or Set as the latest release for the normal one.
  5. Publish, or Save draft to prepare it privately first.

Publishing triggers the release event (types: [published]), so a workflow can build and upload binaries. The same thing from the terminal, using the GitHub CLI:

Terminal
gh release create v1.4.0 --title "1.4.0" --generate-notes
gh release create v2.0.0-beta.1 --prerelease dist/app.zip
gh release upload v1.4.0 dist/checksums.txt
gh release list

Generated release notes and categories

Generate release notes lists the merged pull requests since the previous tag, with contributors. You can group them by label with a file named .github/release.yml:

YAML
changelog:
  exclude:
    labels: [skip-changelog]
    authors: [dependabot]
  categories:
    - title: Breaking changes
      labels: [breaking]
    - title: New features
      labels: [enhancement]
    - title: Bug fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

Labels on pull requests therefore become your changelog sections, which is one more reason to label consistently (the capstone release automation project puts this to work). Good notes explain what changed for users: new options, behavior changes, upgrade steps, and anything deprecated.

Releasing from a workflow

Tag-triggered automation is the usual pattern: pushing v* builds the artifacts and publishes the release.

YAML
name: Release

on:
  push:
    tags: ["v*"]

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build && zip -r app.zip dist
      - env:
          GH_TOKEN: ${{ github.token }}
        run: gh release create "$GITHUB_REF_NAME" app.zip --generate-notes

contents: write is required to create releases. To make a downloaded file provable, add a checksum file or an attestation.

Release hygiene

  • Never move a published tag. People and package managers cache it; publish a new patch version instead.
  • Mark risky builds as pre-releases so latest stays stable.
  • Keep a CHANGELOG.md or rely on release notes consistently; do not do half of each.
  • Protect release tags with a ruleset so only maintainers can create or delete them.
  • Immutable releases (an organization or repository setting) can lock a published release's tag and assets against later changes, when you want that guarantee.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You fix a bug without changing the public interface of version 2.3.1. What is the next SemVer version?

    A backwards-compatible bug fix is a PATCH bump.
  2. 2. Why prefer annotated tags for releases?

    Annotated tags carry metadata that lightweight tags lack.
  3. 3. Which event do workflows use to react to a published release?

    The release event with types such as published triggers on release activity.
  4. 4. What does .github/release.yml configure?

    Its changelog section sets categories and exclusions for automatically generated notes.

Summary

  • Releases combine an annotated Git tag, notes and attached assets; push tags explicitly.
  • SemVer: breaking -> MAJOR, feature -> MINOR, fix -> PATCH; Conventional Commits can drive the bump.
  • Generate notes from merged pull requests and group them with .github/release.yml.
  • Automate with a tag-triggered workflow, never move published tags, and protect release tags.

Next: Organizations, Teams and Permissions