Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 44 ยท Releases and Deployment

Versioning and Automated Releases

Use semantic versioning, conventional commits, tags, changelogs and GitHub Releases to automate releases, plus how release branches fit in.

Shipping software means answering two questions every time: "which version is this?" and "what changed since the last one?" If people answer them by hand, they get them wrong, forget the changelog, and tag the wrong commit. A pipeline can answer both questions the same way every time.

This lesson connects four building blocks: semantic versioning (the numbering rules), conventional commits (commit messages a machine can read), tags (the pointer from a version to a commit), and release automation (changelogs and GitHub Releases). You will also see where release branches fit. The pipeline pieces use triggers from Triggers.

Releases, tags and GitHub Releases cannot be created on this site, so the YAML and commands are read-only. The TryIt blocks are stand-ins: JavaScript programs that compute the next version and build a changelog from commit messages, which is the core logic of tools such as semantic-release and release-please.

Semantic versioning in one minute

Semantic Versioning (SemVer) writes versions as MAJOR.MINOR.PATCH, for example 2.4.1:

  • PATCH goes up for backward-compatible bug fixes: 2.4.1 becomes 2.4.2.
  • MINOR goes up for backward-compatible new features: 2.4.1 becomes 2.5.0 (patch resets to 0).
  • MAJOR goes up for breaking changes: 2.4.1 becomes 3.0.0 (minor and patch reset to 0).

Extra labels follow a dash: 3.0.0-rc.1 is a pre-release and sorts before 3.0.0. A +build suffix (1.2.3+sha.5114f85) is build metadata and is ignored when comparing versions. Versions below 1.0.0 mean "anything may change"; many projects use 0.x while the API is unstable.

SemVer is a promise to the people who depend on you. A library that bumps only the patch number when it removes a function breaks other people's builds, so the number must come from what actually changed, not from a calendar. (Applications that users never "depend on" sometimes use calendar versioning, such as 2025.03, which is also fine if you choose it deliberately.)

Conventional commits: commit messages a machine can read

If commits follow a format, a tool can decide the version bump. The widely used Conventional Commits format is:

TEXT
<type>(<optional scope>)<!>: <short summary>

<optional body>

<optional footer, e.g. BREAKING CHANGE: ...>

Examples:

TEXT
fix(cart): round totals to two decimals
feat(api): add pagination to /orders
feat(auth)!: require tokens on every endpoint
refactor: split pricing module

BREAKING CHANGE: the discount field is now a percentage, not a fraction

The mapping most tools use:

Commit Bump
fix: patch
feat: minor
! after the type, or a BREAKING CHANGE: footer major
docs:, chore:, test:, ci:, refactor: none (not released by themselves)

The highest bump among the commits since the last release wins. Three fixes and one feature produce one minor bump, not four.

JS Compute the next version from commit messages

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

No output.

Run it and look at the last two batches: a breaking change can be written with ! or with a footer, and both produce a major bump. A batch with only chores produces no release at all, which is correct: nothing users can see has changed.

Tags and where releases come from

A tag is a permanent name for one commit. Releases are almost always tags like v2.5.0. The usual pipeline shape:

flowchart LR
    C["Commits on main<br/>(conventional)"] --> T["Tool decides version<br/>and creates tag v2.5.0"]
    T --> W["Tag triggers release workflow"]
    W --> B["Build and test artifacts"]
    B --> P["Publish package or image"]
    B --> R["Create GitHub Release<br/>with notes and files"]

One merge to main can lead to a tag, which triggers a build-once, publish-many workflow.

A workflow that reacts to a version tag and publishes a GitHub Release (read-only):

YAML
name: release
on:
  push:
    tags: ["v*.*.*"]

permissions:
  contents: write   # create the release and upload assets

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0       # full history for notes
      - run: npm ci
      - run: npm test
      - run: npm pack
      - name: Create GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release create "$GITHUB_REF_NAME" ./*.tgz \
            --title "$GITHUB_REF_NAME" \
            --generate-notes

--generate-notes asks GitHub to write release notes from merged pull requests. The tag name is read from GITHUB_REF_NAME through the environment, a habit that keeps untrusted text out of scripts (see Securing Your Pipeline).

One gotcha: a tag pushed by a workflow using the default GITHUB_TOKEN does not trigger other workflows (GitHub blocks this to prevent infinite loops). If your release-creating job pushes the tag, the tag-triggered workflow will not start. Solutions: do everything in one workflow, call the next one with workflow_call, or push using a GitHub App token or personal access token.

Tools that automate the decision

You can write the logic yourself, but several tools already do it:

  • semantic-release: on every push to main it analyzes commits, picks the version, writes notes, tags, and publishes, with no human step.
  • release-please: keeps a standing "release pull request" with the proposed version and changelog. When you merge that PR, the tag and release are created. This gives you a human checkpoint.
  • Changesets: contributors add small files describing a change and its bump; popular for monorepos (see CI for Monorepos).
  • GitHub's own release notes: grouping merged pull requests by label, configured in .github/release.yml.

Whichever you choose, the pieces are the same: a rule that maps changes to a bump, a changelog, a tag, and a publish step.

Build identifiers: which build is this?

A version like 1.4.0 names a release. But CI builds hundreds of artifacts that are never released, and you still need to tell them apart. Three common identifiers, and what each is good for:

Identifier Example Strength Weakness
Build number app-build-145.jar Easy to read, always increasing Tied to one CI server; resets if you move tools
Commit hash app-7662d9e.jar Points at exact source, works anywhere Not sortable, tells you nothing about order
Combined app-1.4.0-2-build-145-7662d9e.jar Version, distance from it, build and source in one name Long

The combined form is the most useful for anything you may need to debug later: from the name alone you know the last release (1.4.0), that the build is 2 commits past it, which CI run made it, and which commit to check out. git describe produces the first half for you. Use the combined form for snapshot and pre-release artifacts, and a clean 1.4.0 (built from the tag) for the real release.

Bash Building identifiers from Git

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

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

In GitHub Actions the same values come from contexts: github.run_number is the build number and github.sha is the full commit hash. In GitLab they are CI_PIPELINE_IID and CI_COMMIT_SHORT_SHA; in Jenkins, BUILD_NUMBER and GIT_COMMIT. Whichever you use, write the identifier into the artifact itself (a manifest, a /version endpoint, an image label) so a running service can say what it is.

Changelogs

A changelog is a human-readable list of what changed in each version. Generated from conventional commits, it groups entries by type. The next TryIt builds one and also shows how version tags should be sorted, because comparing 1.10.0 and 1.9.0 as text gets it wrong.

JS Generate a changelog and sort versions

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

No output.

The text sort puts v1.10.0 before v1.2.0, which is wrong; the SemVer sort fixes it, including placing the release candidate v2.0.0-rc.1 just before v2.0.0. Real tools (the semver library, sort -V) do this for you.

Release branches

With trunk-based development, main is always releasable and you tag straight from it. Some teams need to patch an older version while main has moved on. Then they cut a release branch (for example release/2.x) from the tag, backport only the fix there, and tag v2.4.2 from that branch. Keep these rules:

  • Fix on main first, then cherry-pick to the release branch, so the fix is not lost in the next major version.
  • Run the same pipeline on release branches (use branches: [main, "release/**"]).
  • Delete the branch when that version line is no longer supported.

Avoid long-lived branches for ordinary work. The longer a branch lives, the more painful the merge, which defeats the point of continuous integration.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. The current version is 2.4.1 and the new commits are one fix: and one feat:. What is the next version under SemVer?

    The highest bump wins. A feature is a minor bump, which resets the patch number to 0.
  2. 2. Which commit message signals a breaking change?

    An exclamation mark after the type (or a BREAKING CHANGE footer) marks a major bump.
  3. 3. Why does comparing version strings as plain text fail?

    Characters are compared one by one, so '1.1' comes before '1.2'. Compare each part as a number.
  4. 4. A release workflow creates a tag with the default GITHUB_TOKEN, but the workflow triggered by tags never starts. Why?

    GitHub blocks this to prevent loops. Use one workflow, workflow_call, or a GitHub App or personal token.

Summary

  • SemVer uses MAJOR.MINOR.PATCH: breaking changes, features, fixes. Pre-releases sort before the release.
  • Conventional commits make the bump computable: fix is patch, feat is minor, ! or BREAKING CHANGE: is major.
  • A tag names the exact commit of a release; a tag-triggered workflow builds, tests, publishes and creates the GitHub Release.
  • Tools such as semantic-release, release-please and Changesets automate the decision and the changelog.
  • Use release branches only to patch old versions, and fix on main first.

Next, learn how to put a new version in front of users safely in Deployment Strategies.