Release notes

GitLab release notes are stored in the gitlab repository.

Release notes are organized into one directory for each release with an index.md file and individual files for each feature. For example, the structure is similar to:

doc/
└─ releases/
   └─ 19/
     └─ gitlab-19-0-released/
     │  ├── index.md
     │  └── featureA-Beta.md
     └─ gitlab-19-1-released/
        ├── index.md
        ├── featureB.md
        └── featureA-GA.md

For each release, the product manager is responsible for creating the MR and files for the feature release note. The Technical writing team is responsible for creating all other directories and files.

Create a feature release note

To create a feature release note:

1. Identify the directory for the associated release. It should be something similar to /doc/releases/19/gitlab-19-1-released/.
2. In this directory, create a Markdown file for the feature release note. Although the name doesn’t matter, it’s helpful to name it so it’s identifiable later.
3. Paste the template from below into the Markdown file.
4. Adjust the metadata to match your specific needs.
   • Documentation links must be relative.
   • Make sure work item links are not confidential.
5. After the metadata, define the release note text.
   • Use 125 words or fewer, and no images or videos.
   • Documentation links are allowed, but must be relative.
   • Links to other resources are also allowed.
6. Create a merge request:
   • Use the Release Notes Item template to populate the description and track progress.
   • Assign the merge request to an Engineering Manager and Technical Writer for review.

Edit or remove a feature release note

If you need to update or entirely remove a feature release note, make a merge request with the requested changes, and assign to a Technical Writer for review.

To remove a feature release note, you only need to delete the associated file. No other files need to be adjusted.

Add a notable contributor

Developer Relations creates a merge request for each release that adds a few sentences about the notable contributor. This information needs to be added to the minor release index file. For example, doc/releases/19/gitlab-19-1-released/index.md.

Use the following template after the existing introductory text:

## Notable contributor

We are excited to recognize [Name](https://gitlab.com/<username>)
as this month's [Notable Contributor](https://contributors.gitlab.com/notable-contributors)! ...

This merge request can be merged at any point before the release, though you can check with the author to confirm.

Review a feature release note

After the merge request is created, a Technical Writer must review the metadata and body text. This process is similar to other documentation changes.

Publish release notes

On release day, the Technical Writer assigned to the upcoming release creates three merge requests:

1. Update content for the current release and create content for the upcoming release in gitlab. Can be done before release day.
2. Add current release to navigation in docs-gitlab-com. Can be done before release day.
3. Backport the release notes to the most recent stable branch. For example, if you are releasing 19.1, the stable branch is 19-1-stable-ee. Must be done on release day.

Update content for current release

As part of the publishing process, you must update the minor release index file.

To update the content for the current release:

1. Open the minor release index file. For example doc/releases/19/gitlab-19-0-released/index.md.

2. In the metadata, after the group, add the release date. For example:

   date: 2026-05-21

   This addition makes the pipeline fail until the date of release. This failure is expected.

3. Update the description metadata:

   # Original
   description: Summary of features included in <version>
   
   # New
   desciption: GitLab <version> released with <top feature title>

   Replace the version and top feature title with the relevant information.

4. Update the title metadata:

   # Original
   title: GitLab <version> - not yet released
   
   # New
   title: GitLab <version>

5. Update the introductory text:

   # Original
   The following features are being delivered for GitLab <version>.
   These features are now available on GitLab.com.
   
   # New
   On <release date>, GitLab <version> was released with the following features.

   Replace the date and version with the relevant information.

Create content for upcoming release

As part of the publishing process, you must create the directory and content for the next release. For example, when publishing 19.1, you would create the directory and index file for 19.2.

To create content for the upcoming release:

1. Identify the major version directory in /doc/releases/. For example /doc/releases/19/.

2. Create content for the upcoming version:

   1. Create a new directory for the upcoming release. For example, 19/gitlab-19-1-released/.
   2. In the new directory, create an index.md file for the upcoming release. For example, 19/gitlab-19-1-released/index.md.
   3. Paste the template and update the version number.

3. Add the file to the major version index page.

   1. Go to the major version directory in /doc/releases/. For example /doc/releases/19/.
   2. In _index.md, update the cards shortcode to reference the upcoming release file. For example:
   {{< cards >}}
   
   - [GitLab 19.0](gitlab-19-0-released/index.md)
   - [GitLab 19.1](gitlab-19-1-released/index.md)
   
   {{< /cards >}}

4. Update the upcoming redirect page to reference the upcoming release.

   1. In doc/releases/upcoming.md, update the redirect metadata to point to the upcoming release file. For example:

      ---
      redirect_to: '19/gitlab-19-1-released/index.md'
      ---

5. Create a merge request and assign to a Technical Writer for review.

Add current release to navigation

In the docs-gitlab-com repository, add the current release to data/en-us/navigation.yaml. For example:

        - title: GitLab 19
          url: 'releases/19/'
          submenu:
            - title: GitLab 19.0
              url: 'releases/19/gitlab-19-0-released/'
            - title: GitLab 19.1
              url: 'releases/19/gitlab-19-1-released/'

You can now push your commit. This merge request is complete.

Backport final release notes

After the release notes are published, you must backport them. You must do this work on release day and not before.

The final cutoff for the gitlab repository happens the Friday before the release. If a user selects the version from the upper-right corner of the documentation site, they cannot get the final notes. Backporting makes the notes visible and up-to-date when users select the newly released version.

1. Check out the “stable branch.” For example, if you are releasing 19.1, check out 19-1-stable-ee.
2. Open the latest release notes from the gitlab repository and copy the file contents.
3. Paste the contents over the local version of the release notes.
4. Open a merge request and select the Stable branch template to populate the description. Change the target branch to the stable branch (19-1-stable-ee).
5. Have a maintainer review and merge. (It can be another Technical Writer.) If the branch is still locked, ask for assistance in the #release-post channel, or wait a few hours until the branch is available to merge.
6. After merge, create a new pipeline. For Run for branch name or tag, select the version to deploy. In this example, choose 19.1, then select New pipeline.

Update content after a release

To update, add, or remove a release note after the release deadline:

1. Update the gitlab repository.
   1. Open a merge request to update the Markdown file in the gitlab repository.
   2. Make your changes.
   3. Have a Technical Writer review and merge.
2. Backport the changes.
   1. Check out the stable branch. For example, if you are updating 19.0, check out 19-0-stable-ee.
   2. Make your change in this branch.
   3. Open a merge request and set the target branch to the stable branch (19-0-stable-ee).
   4. Have a maintainer review and merge. It can be another Technical Writer.
   5. After merge, a technical writer must run a new pipeline for the relevant stable branch in docs-gitlab-com. For Run for branch name or tag, select the version to deploy. In this example, choose 19.0, then select New pipeline.
3. On https://docs.gitlab.com, select the version in the upper-right corner and verify the notes were updated successfully.

Organization

In the release post, each feature release note is grouped into a section based on the stage metadata defined in the feature release note. Each stage maps to one of the following sections:

Sections appear in the order listed in the table, with Primary features first. Any stage that isn’t mapped appears in the Scale and Deployments section. To add features to the Primary features section, use the level metadata.

In each section, feature release notes are listed alphabetically by title. To override this order, define a value for the weight metadata, where lower numbers go first.

Generally, use multiples of 10 (such as 10, 20, 30) to leave room for future insertions, and avoid single-digit values unless a note must absolutely appear first.

Metadata

Minor release index metadata

Feature release note metadata

Templates

Minor release index

---
title: "GitLab <version> - not yet released"
description: "Summary of features included in <version>"
group: Monthly Release
stage: Release Notes
---

The following features are being delivered for GitLab <version>.
These features are now available on GitLab.com.

## Notable contributor

Feature release note

---
title:
tier: [ Free, Premium, Ultimate ]
offering: [ gitlab_com, self_managed, gitlab_dedicated, gitlab_dedicated_for_government ]
stage: application_security_testing
documentation_link: "../../../_index/#popular-topics"
work_item: https://gitlab.com/groups/gitlab-org/-/work_items/<work-item-number>
categories: [ System Access, Permissions ]
level: primary or secondary
weight: 50
ignore_in_report: true
---

<!-- categories: System Access, Permissions -->

The text of the feature release note.

Explain the value of this improvement with 125 words or fewer.
Use phrases that start with, "In previous versions of GitLab, you couldn't... Now you can..."