How to write GitLab release notes and keep a changelog
A GitLab release is a tag plus notes you write, and GitLab can generate CHANGELOG.md from commit trailers. Below: a copy-paste release notes template, the trailer and CI setup, the mistakes that make entries go missing, and four GitLab projects to copy.
Updated Last checked 8 min readOpen-source libraries and packages
Copy-paste GitLab release notes template
Paste this into the release notes field, or save it as a file and pass it to a CI job's release:description. In GitLab's Markdown, !140 links merge request 140 and #87 links issue 87, so you don't need full URLs. Breaking changes go first, each with what to change.
## What's new in 3.0.0
Two breaking changes: `export` needs `--format`, and `--legacy` is gone.
Most projects need one line changed; see "Upgrade from 2.x".
### Breaking changes
- `export` fails without `--format`. Add `--format json` to keep the old output (!140).
- `--legacy` is removed. It was deprecated in 2.2.0; delete it from your scripts (!139).
### Added
- `export --format csv` writes CSV as well as JSON (!142).
### Fixed
- `import` no longer stops at the first empty line (#87, !141).
### Security
- Updated libyaml to fix CVE-YYYY-NNNNN (!143). Delete this heading if there's nothing to report.
### Upgrade from 2.x
1. Add `--format json` to every `export` call in scripts and CI jobs.
2. Remove `--legacy` wherever you pass it.
**Full changelog:** https://gitlab.com/GROUP/PROJECT/-/compare/v2.4.1...v3.0.0The project, versions, merge requests and the CVE are placeholders. Replace them with what you actually shipped.
The short answer
- Release notes are Markdown you write: in Deploy > Releases, through the Releases API, or from a CI job's
release:keyword, whosedescriptioncan be a file path. - GitLab's changelog generator lists only commits with a
Changelog:trailer (added, fixed, changed, deprecated, removed, security, performance or other) and writes them to CHANGELOG.md through the API orglab changelog generate. - Tags must look like semantic versions (
v1.2.3or1.2.3) unless you settag_regex. Pre-release tags are ignored when GitLab works out which commits to include. - The generator lists commit titles. Breaking changes and upgrade steps still need a person: add them to the release notes by hand.
- If a CI job creates the release, don't type release notes when you create the tag in the UI: that creates the release first and the pipeline fails.
- Deleting a tag deletes its release, so fix a release by editing it, not by re-tagging.
Free tool · no sign-up
Can a coding agent read your changelog?
Paste your repository, a GitHub release or a CHANGELOG.md link. The free converter shows every version, breaking change, migration step and deprecation it can extract, as JSON plus an llms.txt summary.
No AI, and your changelog isn't stored. Or paste a CHANGELOG.md instead
01Where release notes live on GitLab
GitLab has three places for ‘what changed’, and they're for different readers. A release is tied to a tag: GitLab's docs warn that “deleting a Git tag associated with a release also deletes the release.”
| Place | Who reads it | How it's written |
|---|---|---|
| The release (Deploy > Releases) | Users and anyone subscribed to new releases | By hand, through the Releases API, or from a CI job's release: keyword |
| CHANGELOG.md in the repository | Contributors, packagers and tools | By hand, or generated from Changelog: trailers |
| Merge request and tag messages | The team | As you work; the raw material for the other two |
People who want an email for every release can set their notification level for the project to Custom and tick ‘New release’. That makes the release notes your announcement, so write them for users, not for the team.
02Generate CHANGELOG.md from Changelog: trailers
GitLab's built-in changelog generator works from Git trailers, a line at the end of the commit message. Only commits with the trailer are included, and the entry uses the commit's title, linked to the commit and its merge request.
Add CSV output to the export command
Users asked for spreadsheets; JSON stays the default.
Changelog: added- The values are added, fixed, changed, deprecated, removed, security, performance and other.
- If a merge request has several commits, GitLab's docs say to put the trailer on the first commit, so the entry survives squashing.
- Out of the box the headings are the raw values, like
### added (2 changes). Map them to the names readers know in.gitlab/changelog_config.yml. - Generate the section when you're ready to release: the API's POST endpoint commits it to CHANGELOG.md on the default branch with the message “Add changelog for version X”, and
glab changelog generate > preview.mdshows it locally first. Then tag the release.
---
date_format: "%Y-%m-%d"
categories:
added: Added
changed: Changed
deprecated: Deprecated
removed: Removed
fixed: Fixed
security: Security
performance: Performance
other: Othercurl --request POST \
--header "PRIVATE-TOKEN: <your-token>" \
--data "version=3.0.0" \
--url "https://gitlab.com/api/v4/projects/<project-id>/repository/changelog"## 3.0.0 (YYYY-MM-DD)
### Added (1 change)
- [Add CSV output to the export command](GROUP/PROJECT@abc1234) ([merge request](GROUP/PROJECT!142))
### Fixed (1 change)
- [Keep reading after an empty line in import](GROUP/PROJECT@def5678) ([merge request](GROUP/PROJECT!141))That's a good changelog for contributors, but not yet good release notes: there's no summary, no upgrade steps, and a removal is just another commit title. Start the release notes from it and add those by hand, using the template above. The changelog format guide explains the sections; the free validator checks the file.
03Publish the release from CI
A CI job with the release: keyword creates the release when the pipeline runs for a tag. GitLab's examples run it in the registry.gitlab.com/gitlab-org/cli:latest image, which contains the glab CLI; the older release-cli tool is listed as deprecated.
release:
stage: deploy
image: registry.gitlab.com/gitlab-org/cli:latest
rules:
- if: $CI_COMMIT_TAG
script:
- echo "Creating release $CI_COMMIT_TAG"
release:
tag_name: $CI_COMMIT_TAG
description: ./release-notes.mddescriptiontakes text or a file path relative to the project directory. A file with your notes for this tag keeps long notes out of the YAML.- The release is created only if the job succeeds; if the API returns an error, the job fails.
- Creating tags in the UI? Leave the release notes field empty, or GitLab creates the release before your job and the pipeline fails.
04Let a CI component write the notes from CHANGELOG.md
Writing a release-notes.md for every tag gets old. The free LogPulse GitLab CI/CD component does it on each tag pipeline: it takes the matching section of CHANGELOG.md, puts breaking changes and their migration steps first, and creates or updates the GitLab release. It reads hand-written Keep a Changelog sections and the sections GitLab's changelog generator writes, including headings like ### Added (1 change).
- GitLab Catalog listing coming soon: download it from the component page, save the template as
.gitlab/ci/release-notes.ymland include it withinclude: local. - No changelog section for the tag? With
source: auto(the default) it falls back to the commits since the previous tag, grouped by Conventional Commits type, with each merge request listed once. - In a monorepo, include it once per package with its own
job-name,changelog-pathand tag pattern. Monorepo changelogs covers the tags. - Set
release-tool: glabto publish with GitLab's newer CLI instead of release-cli.
05Common mistakes that make entries go missing
Most ‘why isn't my change in the changelog?’ questions come down to one of these.
- Tags that don't look like versions. GitLab ignores tags that don't match its semantic-version pattern, so
release-3.0never counts as a release. Rename your tags or settag_regexin the config. - Expecting a release candidate to start the range. Tags with a pre-release part, like
v3.0.0-rc.1, are skipped when GitLab decides which commits to include. - A trailer on the wrong commit. In a merge request with several commits, put
Changelog:on the first one, or it can disappear when the commits are squashed. - A reverted change. GitLab leaves out commits that are both added and reverted in the range, which is usually what you want, but surprising if the revert was partial.
- A hand-written CHANGELOG.md with
## v1.2.3headings. GitLab's docs say new sections are then appended to the end of the file instead of the top. Use## 1.2.3headings before switching to generated entries. - Commit titles as release notes. ‘Refactor exporter’ tells users nothing. Rewrite titles into what changed for them, and add upgrade steps for every breaking change.
06Generate the release notes from your commits
Not using trailers? You can still get a first draft from git in a minute, then spend your time on the breaking changes and upgrade steps.
# Full messages, so BREAKING CHANGE: footers come along
git log v2.4.1..HEAD --no-merges- Paste the output into the free changelog from commits tool and add your GitLab project's address. You get release notes and a CHANGELOG.md section, with
feat!:commits andBREAKING CHANGE:footers as breaking changes and a compare link between your tags. - Edit the draft into the template above: a one-line summary, breaking changes with what to change, then the rest.
- Save it as CHANGELOG.md's new section, push the tag, and let the component or your release job publish it.
- Want an AI coding agent to read it too? The free changelog converter turns CHANGELOG.md into JSON with breaking changes and migration steps as fields. More in changelogs for AI coding agents.
Real projects that do this well
Public release notes worth copying from. Each link opens the project's own page.
- GitLab GitLab's own CHANGELOG.md is generated from Changelog: trailers: a heading per version with its date, Added, Fixed and Changed sections with change counts, and a link to each commit and merge request.
- GitLab Runner Categories named for readers rather than Keep a Changelog (New features, Bug fixes, Maintenance), a dated heading per version, and every line ending with a link to its merge request.
- GitLab CLI (glab) Release notes grouped by commit type (Features, Maintenance and so on), each line a Conventional Commits title with its commit link and author, and the built packages attached to the release.
- F-Droid client An Android app's changelog written for users: short, plain-language lines per version with no categories, release candidates listed too, and 2.0.0 opening with what carries over from 1.x installs.
Before and after
Too vague
v3.0.0: Refactor exporter (!140). Remove legacy flag (!139). Add CSV (!142).
Specific and actionable
3.0.0 has two breaking changes: export needs --format (add --format json to keep the old output), and --legacy is gone (delete it from your scripts). New: export --format csv.
Fictional example: use your own verified names, versions and behavior.
LogPulse
Generate release notes with LogPulse
LogPulse is a hosted changelog that people and coding agents can both read. Here's exactly what it can do for the steps above, and what it can't.
Check your changelog, free
Paste a CHANGELOG.md or a GitHub releases link. A deterministic parser (no AI; your changelog isn't stored) shows the versions, breaking changes, migration steps and deprecations an agent can extract.
Draft notes from GitHub
Connect a repository: merged pull requests, commits to your default branch and published GitHub releases collect in an inbox. AI drafts a note in the tone you pick, listing breaking changes and deprecations only when the changes clearly show them. Nothing is published until you approve it. 3 AI drafts on Free; unlimited on Open source and Pro. Pro opens soon: .
Publish once, read everywhere
Approved notes go to a hosted changelog and an in-app widget, to email subscribers on Open source and Pro (Pro opens soon), and to a JSON feed and MCP server coding agents can query. CI and agents can publish with an API key.
What it doesn't do: LogPulse doesn't tag releases, bump versions, publish to npm or PyPI, or write CHANGELOG.md back to your repository; keep your release tooling for those. AI drafts can miss context, so review them like a pull request.
Before you publish
- Tags look like semantic versions, or tag_regex matches them
- Changelog: trailers are on the first commit of each merge request
- Category names are mapped in .gitlab/changelog_config.yml
- The release notes open with a summary and list breaking changes first
- Every breaking change says what to change
- Tags created in the UI leave the release notes empty when CI creates the release
Common questions
Can GitLab generate release notes automatically?
GitLab generates changelog sections from commits that carry a Changelog: trailer, through the API or glab changelog generate. It doesn't write the release notes field for you; use the generated section as a starting point, or a CI job (or the free LogPulse component) that copies it into the release.
Why is my commit missing from the generated changelog?
Usually because it has no Changelog: trailer, the trailer was on a later commit of a squashed merge request, the commit was reverted in the same range, or the tags don't match GitLab's version pattern.
Where do people see GitLab release notes?
On the project's Releases page (Deploy > Releases) and from the release count on the project overview. People who set their notifications to Custom with New release ticked also get them by email.
Sources
Facts last checked against these sources on .
Next step
Automate this on every release
Skip the copy-paste next time: let your pipeline write the release notes when you tag. Free, no LogPulse account.
- GitHub ActionWrites each GitHub release from CHANGELOG.md or the pull requests merged since the last tag.Set it up
- GitLab componentThe same notes for GitLab releases, in a tag pipeline. Only needs CI_JOB_TOKEN.Set it up
- Free API & MCPRelease notes, changelog checks and conversion over HTTP or MCP. No key, no account.Read the docs
- A draft from every merged pull request, published to your widget, hosted changelog and subscribers' inboxes.€12/month or €99/year + VAT · opens soonJoin the waitlist
Read next
How to write release notes for open-source libraries
Copy-paste release notes template for open-source libraries, 4 annotated examples modelled on Node.js, Django, Python and Vite, and a free generator.
Read the guide Open-source libraries and packagesHow to write release notes from commits (Conventional Commits)
Turn commits into release notes: the Conventional Commits format, how feat, fix and ! map to versions and sections, tools that automate it, what to edit.
Read the guide Open-source libraries and packagesHow to generate a changelog from git commits
Generate a changelog from git: find the last tag, list commits since it with git log, credit contributors with git shortlog, use GitHub's generated notes, then edit.
Read the guide Open-source libraries and packagesKeep a Changelog vs GitHub Releases
CHANGELOG.md or GitHub Releases? See them side by side, when to use each, and how to keep both in sync with release.yml. Includes a CHANGELOG.md skeleton.
Read the guide Open-source libraries and packagesHow to keep a changelog in a monorepo
One changelog or one per package? A copy-paste per-package CHANGELOG.md, tag formats for Changesets, Nx and release-please, and 4 real monorepo examples.
Read the guideMore guides: open-source libraries and packages
- Changelog vs release notes: what's the difference?
- CHANGELOG.md format, explained line by line
- Release notes templates in Markdown
- semantic-release vs release-please vs Changesets (and git-cliff)
- How to keep a changelog for an npm package
- How to keep a changelog for a Python package on PyPI
- How to keep a changelog for a Rust crate
Tools and resources
- Free GitLab CI/CD component: release notes from CHANGELOG.md
- Free tool: changelog from git commits
- Free tool: Keep a Changelog validator
- CHANGELOG.md format, explained line by line
- Free tool: convert a CHANGELOG.md or GitHub release to JSON
- Free tool: GitHub release notes generator for any two releases
- Free GitHub Action: release notes from your CHANGELOG.md on every tag
- kalmwerk/release-notes-action on GitHub: the Action's code and releases
- Free tool: a GitHub repo's changes since its last tag, as a changelog
- LogPulse developer docs: feed, API and MCP server
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.