Tags and releases
Intermediate GitLab UI
Why this matters
Release notes are frequently a documentation person's job, and they are the one artefact users actually read. Knowing where the raw material lives, and how GitLab turns a tag into a release page, turns an hour of guesswork into fifteen minutes of editing.
Tag, then release
A tag is Git's permanent name for a commit (lesson 6.2, command page). A release is GitLab's page built on top of one, with notes, dates, links and files.
| Tag | Release | |
|---|---|---|
| Belongs to | Git | GitLab |
| Is | a name for a commit | a page describing what that commit contains |
| Created by | git tag and a push, or the web |
Deploy → Releases → New release, or a pipeline job |
| Visible to | anyone who clones | anyone who can see the project |
Every release has a tag; not every tag has a release. Creating a release from the web can create the tag at the same time, which is how most teams do it.
Making one
Deploy → Releases → New release asks for:
| Field | What to put |
|---|---|
| Tag name | The version, conventionally v1.3.0 (lesson 13.6) |
| Create from | The branch or commit the tag should mark, usually main |
| Release title | The version, or the version plus a short theme |
| Milestones | The milestone this release delivers, which pulls in its issues |
| Release notes | The prose users read; Markdown |
| Assets | Links to downloads, documentation, the container image |
Attaching the milestone is the trick worth knowing: the release page then lists the issues and merge requests it contained, which is both a checklist and half the notes written for you.
Releases can also be created by a pipeline job when a tag is pushed, so that shipping is one git push origin v1.3.0. If your project does that, the notes usually come from a CHANGELOG.md in the repository, and editing that file is how you write them.
What to write in release notes
Users want to know what changed for them, not what changed in the code:
## What's new
- The trail list can be filtered by difficulty: `--difficulty hard`.
- The installation guide now covers Windows.
## Fixed
- The list no longer crashes when a trail has no distance (#15).
## Upgrading
No action needed. If you scripted the old `--level` option, it is now `--difficulty`.Three sections cover most releases: what is new, what is fixed, and anything the reader must do. Link issue numbers so the curious can follow; keep the entries in the user's vocabulary rather than the code's.
Finding out what shipped
Whether you are writing the notes or answering "is my fix in 1.3?", the same three tools:
| Question | Where |
|---|---|
| Which issues were in this release? | The milestone attached to it, or Plan → Milestones |
| Which merge requests were merged since the last one? | Code → Compare revisions, from v1.2.0 to v1.3.0 |
| Which commits, exactly? | git log --oneline v1.2.0..v1.3.0 |
| Does version X contain commit Y? | git tag --contains <hash> |
$ git fetch --tags
$ git log --oneline v1.2.0..mainThat range is the honest list of what has accumulated since the last release, and it is where release notes start.
How to do it
Tags are Git; releases are not. To create and publish a tag:
$ git tag -a v1.3.0 -m "Release 1.3.0: Windows FAQ and licence wording"
$ git push origin v1.3.0To https://gitlab.com/you/trailguide.git
* [new tag] v1.3.0 -> v1.3.0Remember that a plain git push does not send tags (command page). Once the tag is on GitLab, the release page can be created from it.
Git: Create Tag in the Command Palette, then push with Git: Push (Follow Tags). Releases themselves are a web feature; the GitLab Workflow extension does not create them.
Git → New Tag… on the current commit, or right-click a commit in the Log → New Tag…. Tick Push Tags in the push dialog. Releases are created on the web.
- Deploy → Releases → New release.
- Choose or create the Tag name, and the branch or commit to create it from.
- Attach the Milestone so the release lists its issues and merge requests.
- Write the Release notes in Markdown.
- Add Assets if there are downloads or documentation links.
- Create. The tag now appears under Code → Tags and the release under Deploy → Releases.
The same two-step idea: a tag, then a Release built on it under the repository's Releases section, with a Generate release notes button that drafts notes from merged pull requests. See lesson 10.9.
Common mistakes
- Assuming
git pushsends tags. It does not; push the tag explicitly. - Notes written from the commit log. Commit subjects are for developers; users want outcomes.
- Moving a published tag to "fix" a release. Everyone who fetched it keeps the old one; ship a new version instead (command page).
- A release with no milestone attached, so the page cannot list what it contained.
- Forgetting the upgrade note when something a user depends on changed name or behaviour.
Try it yourself
Goal: cut a release of your practice project and write its notes.
- Make sure
mainhas a few commits since your last tag, or make two small commits. - In the terminal:
git tag -a v1.3.0 -m "Release 1.3.0"andgit push origin v1.3.0. - On GitLab: Deploy → Releases → New release, choose the existing tag
v1.3.0, and write notes with "What's new" and "Fixed" sections. - Attach a milestone if you made one in lesson 9.6.
- Run
git log --oneline v1.2.0..v1.3.0(or from your earliest tag) and compare it with what you wrote.
Expected result: a release page with your notes, and a command-line list of commits that matches what you described in user-facing language.
Show solution
Step 5 is the useful comparison: the commit list is the raw material and your notes are the translation. If a commit in the list has no counterpart in the notes, either it did not matter to users, which is fine and worth noticing, or you missed it.