GitLab Tags and Releases

A tag is a permanent name attached to one exact commit. A release builds on a tag and adds notes, download files, and a public page that tells users what changed. Tags mark the moment. Releases announce it.

Think of a book. A tag works like a bookmark placed on the page where edition 1.0 was printed. A release works like the back-cover summary that lists the new chapters and the files you can download.

Branches and Tags Compared

  main:   A ── B ── C ── D ── E ── F ── G
                    ▲                ▲
                  v1.0.0           v1.1.0
  (a branch moves forward with each commit; a tag stays on one commit)
ItemMoves with new commits?Typical Use
BranchYesOngoing work
TagNoFixed version marker

Semantic Versioning

Most teams name versions with three numbers: MAJOR.MINOR.PATCH.

  v2.4.1
   │ │ └── PATCH: bug fixes only
   │ └──── MINOR: new features, old features still work
   └────── MAJOR: big changes that may break old behavior

A bug fix moves 2.4.1 to 2.4.2. A new feature moves 2.4.2 to 2.5.0. A breaking change moves 2.5.0 to 3.0.0.

Create a Tag

Lightweight Tag

A lightweight tag stores only a name.

git tag v1.0.0

Annotated Tag

An annotated tag stores the author, the date, and a message. Teams prefer this type for releases.

git tag -a v1.0.0 -m "First stable version"

Upload the Tag to GitLab

Tags stay on your computer until you push them.

git push origin v1.0.0
git push origin --tags

The second command uploads every local tag at once.

Create a Tag in the GitLab Page

  1. Open Code and select Tags.
  2. Select New tag.
  3. Type a tag name and choose the branch or commit to mark.
  4. Add a message and select Create tag.

Manage Tags

TaskCommand
List all tagsgit tag
Show tag detailsgit show v1.0.0
Delete a local taggit tag -d v1.0.0
Delete a remote taggit push origin --delete v1.0.0
Check out code at a taggit checkout v1.0.0

Maintainers can protect tags in Settings → Repository → Protected tags. A protected tag blocks changes and deletion by regular members.

Create a Release

  1. Open Deploy and select Releases.
  2. Select New release.
  3. Pick an existing tag or type a new tag name.
  4. Enter a release title such as "Version 1.0.0".
  5. Write release notes in Markdown.
  6. Attach asset links for installers or documentation.
  7. Select Create release.

Write Clear Release Notes

## Version 1.2.0

### New
- Dark mode for the dashboard
- CSV export for reports

### Fixed
- Login page no longer freezes on slow networks

### Changed
- Search results load 40 percent faster

Group changes under plain headings. Readers scan for the fixes that affect them.

Automate Releases with CI/CD

A pipeline job creates the release whenever someone pushes a version tag.

create-release:
  stage: deploy
  image: registry.gitlab.com/gitlab-org/release-cli:latest
  script:
    - echo "Creating release for $CI_COMMIT_TAG"
  release:
    tag_name: $CI_COMMIT_TAG
    description: "Release $CI_COMMIT_TAG"
  rules:
    - if: $CI_COMMIT_TAG

The rule limits the job to tag pushes. The variable CI_COMMIT_TAG carries the tag name into the release.

Release Habits That Work

  • Tag only code that passed the full pipeline.
  • Use the same naming pattern for every tag.
  • Never move or reuse a published tag.
  • Link each release to its milestone and closed issues.
  • Keep a changelog that users can read without technical knowledge.