Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 36 ยท Packages and Registry

Releases and Semantic Versioning

Publish GitLab releases from tag pipelines with the release keyword, attach asset links, follow semantic versioning, and generate a changelog from conventional commits.

A release is how you tell the world "version 2.3.0 exists, here is what changed, and here are the files". In Git, the anchor is a tag: a name that points to one commit forever. In GitLab, a release adds a page on top of a tag with notes, links and downloadable assets, and the release can be created by a pipeline so nobody has to click through forms.

This lesson covers semantic versioning, creating tags, the release keyword, asset links, milestones, and generating a changelog. GitLab cannot run here, so the YAML is read-only; the examples are runnable JavaScript stand-ins for the version arithmetic and the changelog.

Semantic versioning in two minutes

Semantic versioning (SemVer) writes versions as MAJOR.MINOR.PATCH:

  • PATCH (2.3.0 to 2.3.1): bug fixes that change no behavior others rely on.
  • MINOR (2.3.1 to 2.4.0): new features that stay backward compatible; the patch resets to 0.
  • MAJOR (2.4.0 to 3.0.0): breaking changes; minor and patch reset to 0.

A pre-release uses a hyphen suffix (3.0.0-rc.1) and sorts before 3.0.0. Build metadata after a plus sign (3.0.0+20260601) is ignored when comparing. Versions starting with 0. mean "anything may change". The benefit of the scheme is that users can read the risk of an upgrade from the number alone. Tag names conventionally add a v: v2.4.0.

Tags and releases

Create a tag from the command line and push it:

Terminal
git tag -a v2.4.0 -m "Release 2.4.0"
git push origin v2.4.0

An annotated tag (-a) stores the tagger, date and message, and is the right choice for releases. Pushing the tag starts any pipeline whose rules match $CI_COMMIT_TAG. Protect the pattern v* so only trusted roles can create release tags (see Roles, Permissions and Protected Branches).

A release in GitLab is an object attached to a tag. Under Deploy > Releases you see each release with its notes, the source code archives GitLab generates automatically, and any links you add. A release can also point to milestones, so the page lists the issues closed in that version.

Creating a release from the pipeline

The release keyword in a job creates the release when the job succeeds:

YAML
create_release:
  stage: release
  image: registry.gitlab.com/gitlab-org/cli:latest
  rules:
    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
  script:
    - echo "Creating release for $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    name: "Release $CI_COMMIT_TAG"
    description: "Notes are generated from the changelog."
    assets:
      links:
        - name: "Linux binary"
          url: "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/mytool/${CI_COMMIT_TAG}/tool-linux-amd64"
          link_type: package
        - name: "Container image"
          url: "https://${CI_REGISTRY_IMAGE}:${CI_COMMIT_TAG}"
          link_type: image

Points to know:

  • The job's image must contain GitLab's release tooling (the command-line client glab, or the older release-cli). Check the documentation for the tool your version expects.
  • rules with a tag pattern keep the job from running on branches; the regular expression above accepts only vX.Y.Z tags.
  • assets.links do not upload files; they point to files you already published, for example in the generic package registry (see Package Registry) or the container registry (see Container Registry). link_type can be package, image, runbook or other.
  • The release job should run after the jobs that build and publish the assets, using needs or a later stage, otherwise the links would point to files that do not exist yet.
flowchart LR
  T["push tag v2.4.0"] --> B["build"]
  B --> P["publish package and image"]
  P --> R["create_release job"]
  R --> RP["release page with notes and asset links"]

The release job comes last, once everything it links to exists.

Conventional commits and changelogs

Writing release notes by hand is slow and forgets things. If commit messages follow a pattern, a tool can compute both the next version and the changelog. The popular pattern is Conventional Commits:

TEXT
feat(search): add fuzzy matching
fix(auth): refuse expired tokens
feat(api)!: remove the v1 endpoints

BREAKING CHANGE: clients must use /v2
docs: explain the retry setting

The rules: fix bumps PATCH, feat bumps MINOR, and anything marked with ! or a BREAKING CHANGE: footer bumps MAJOR. Other types (docs, chore, test, refactor) do not trigger a release by themselves. GitLab also has a changelog API that builds notes from commits that carry a trailer (Changelog: added), and tools such as semantic-release or git-cliff do the same job in a pipeline. Whichever tool you choose, the principle is identical: commit messages are data.

With squash merges, the merge request title becomes the commit message on main, so enforce the pattern on the title (a small CI job or a push rule) rather than on every commit.

Stand-in: bumping a version

The first example implements the SemVer bump rules and a comparison that treats pre-releases correctly.

JS Semantic version arithmetic

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

No output.

The second example reads a list of conventional commit messages, decides the next version, and writes grouped release notes.

JS Next version and changelog

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

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. The current version is 2.3.1 and you add a backward-compatible feature. What is next?

    A new compatible feature raises the MINOR number and resets PATCH to 0.
  2. 2. Which version is the oldest of these: 3.0.0, 3.0.0-rc.1, 2.9.9?

    2.9.9 has a lower major number. A pre-release such as 3.0.0-rc.1 is older than 3.0.0 but newer than any 2.x version.
  3. 3. What do assets.links in the release keyword do?

    Links only point to files; publish them first to a package registry, container registry or another location.
  4. 4. Why should the release job run after the publish jobs?

    A release page with broken links is worse than none, so order the jobs with stages or needs.
  5. 5. A commit message reads feat(api)!: remove the v1 endpoints. Which bump does it cause?

    The exclamation mark marks a breaking change, which calls for a major version.

Summary

  • SemVer encodes risk: patch for fixes, minor for compatible features, major for breaking changes.
  • Annotated tags anchor releases; protect v* tags and trigger release pipelines with $CI_COMMIT_TAG.
  • The release keyword creates the release page and assets.links point at published files.
  • Conventional commits let tools compute the next version and the changelog automatically.

Next: Self-Managed Installation and Backups