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)
| Item | Moves with new commits? | Typical Use |
|---|---|---|
| Branch | Yes | Ongoing work |
| Tag | No | Fixed 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
- Open Code and select Tags.
- Select New tag.
- Type a tag name and choose the branch or commit to mark.
- Add a message and select Create tag.
Manage Tags
| Task | Command |
|---|---|
| List all tags | git tag |
| Show tag details | git show v1.0.0 |
| Delete a local tag | git tag -d v1.0.0 |
| Delete a remote tag | git push origin --delete v1.0.0 |
| Check out code at a tag | git 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
- Open Deploy and select Releases.
- Select New release.
- Pick an existing tag or type a new tag name.
- Enter a release title such as "Version 1.0.0".
- Write release notes in Markdown.
- Attach asset links for installers or documentation.
- 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.
