Monthly releases

Monthly Release Policy

Monthly releases are the vehicle for delivering new features, bug fixes, and performance improvements to self-managed customers. Unlike patch releases and internal releases, monthly releases can include new functionality.

For the general release policy framework including ownership, exception process, and escalation paths, see the Release Policy section.

Monthly release overview

The monthly release is a semver versioned package containing changes from many successful deployments on GitLab.com. Users on GitLab.com, therefore, receive features and bug fixes earlier than users of self-managed installations.

The deployments and releases page details how the two processes work together.

Relationship to Other Release Types

Monthly releases create the foundation for all other release types:

• Stable branches are created when the release candidate is tagged, forming the basis for patch and internal releases
• Patch releases are cut from these stable branches to deliver bug and security fixes to self-managed customers
• Internal releases use the same stable branches to deliver critical fixes to GitLab Dedicated before public disclosure

Monthly release schedule

Monthly release process

The monthly release timelines are concentrated around the release date.

Overview of the steps involved on the monthly release process:

• Diagram source

The end-to-end process consists on the following stages:

1. First steps - Initial steps to setup the monthly release, including setting up the release schedule and the deployment cadence.
2. GitLab.com deployments - From the start of the milestone up to one week before the release date, GitLab.com receives multiple deployments per day. For application changes to be included in a monthly release they need to be successfully deployed to GitLab.com.
3. Release candidate - A test release candidate (RC) is created, along with a stable branch for the targeted semver version. The release candidate package is built, tested and deployed to the pre environment. A successful outcome indicates this package can be used as the final version. At this point Release Managers will announce the final commit to be included in the release.
4. Tag - Release Managers tag the final version of the release based on the release candidate. The release is built and deployed to the Release environment.
5. Release - On the release day, the release packages are published.

Release Steps

Release Preparation (Up-to and including Tuesday of Release Week)

This provides a window to validate changes, address bugs, and ensure stability in what is destined to be released. Cutting our first RC is when the stable branch of that version is created. Many RC’s can be created to address bugs that arise. It should be noted that once the first RC is created, any bugs need to be directly ported to the stable branch. No new features will be included at this stage.

Tag Day (Third Wednesday)

This day is our point of no return. Once a tag is created it is immutable. All changes destined for the release are set in stone.

Release Day (Third Thursday)

Timelines

The only guaranteed date throughout the release cycle is the release date. On this date, the monthly release will be published together with the release announcement.

All other dates are a guideline only and cannot be considered a deadline when it comes to what will be included into any type of release. This includes the development month and the dates defined there as well as any promises given to customers. This is strictly because there are a lot of moving parts to be considered when preparing a release which includes working on highest priority and severity issues as well as security related issues.

If it is absolutely necessary to get a certain feature ready for a specific version, merge the feature early in the development cycle. Merges closer to the release date are absolutely not guaranteed to be included in that specific monthly release.

How can I determine if my merge request will make it into the monthly release?

Multiple tools are available to help determine if the merge request will be included in the upcoming monthly release. This section consolidates all available tooling for easy reference.

Available tooling

1. Labels on merge requests
2. Merge request widget
3. ChatOps commands
4. Release dashboard
5. Slack announcements on #releases channel

Labels indicating inclusion in upcoming monthly release

Merge requests included in a release candidate (RC) will be part of the monthly release. See “What is a release candidate and when are they created?” for more information on release candidates. Merge requests will receive the released::candidate label to indicate their inclusion into the RC.

A merge request will receive the released::published label (which replaces the released::candidate label) when included in the final release, such as 13.6.0 or 13.5.2, and deployed to release.gitlab.net.

Merge request widget

The merge request widget shows the environment and the time of deployment in every merge request. This provides information to understand where in the release process any merge request is:

• release is for the final version that is going out for self-managed users. When an MR is deployed to release.gitlab.net instance, the released::published label is applied to the MR to indicate that it will be included in the upcoming monthly release.
• pre is for release candidates and versions that are used as a preparation for a final release for self-managed users. When an MR is included in a release candidate, the released::candidate label is applied to the MR to indicate that it will be included in the upcoming monthly release.

The merge request widget can also be used to reference where in the deployment process any merge request is:

• gstg-cny is the canary stage of the GitLab SaaS staging environment
• gprd-cny is the canary stage of the GitLab SaaS production environment
• gstg is the staging environment for GitLab SaaS - staging.gitlab.com
• gprd is the production environment for GitLab SaaS - GitLab.com
• db/gstg indicates post migrations included in the merge request have been executed in the staging environment.
• db/gprd indicates post migrations included in the merge request have been executed in the production environment.

No environment in the widget means that the MR is not deployed to any environment yet

ChatOps commands

GitLab team members can use ChatOps commands in the Slack #releases channel to check the status of merge requests.

Check the MR status with respect to monthly releases

There is a ChatOps command that can be used to check the status of an MR with respect to monthly releases:

/chatops run release check <MR URL> <upcoming release version (optional)>

For example: /chatops run release check https://gitlab.com/gitlab-org/gitlab/-/merge_requests/12345 14.4.

MRs from the gitlab-org/gitlab, gitlab-org/security/gitlab, gitlab-org/omnibus-gitlab and gitlab-org/security/omnibus-gitlab projects are supported by this command.

Two scenarios where this command can be useful:

1. Check which version an MR was first released in: /chatops run release check <MR URL> (when the version is omitted, it will only check if the MR has already been released)

2. Check the likelihood of an MR being included in the upcoming monthly release: /chatops run release check <MR URL> <upcoming release version>

Monthly release information dashboard

GitLab team members can view the internal Grafana dashboard “Release Information” for the following information:

• Upcoming monthly release version
• Upcoming monthly release date
• Upcoming monthly release due date
• Current status of the upcoming monthly release

The due date for merge requests to be included in the upcoming monthly release is set to the date when the initial release candidate and the stable branches are created. Past that point, no more features will be included in the monthly release.

The monthly release dashboard also contains a panel that describes the current status whether it is open and accepting deployed merge requests or if it’s already closed and no new features can be added.

The metrics used to display this information are updated automatically throughout the monthly releases process.

Slack announcements on #releases channel

In the runup to the release date, Release Managers will announce the final commit to make it into the release. Such notifications are shared in Slack #releases channel and will look something like this (format is defined in the release-tools monthly template):

📣 The stable branch has been created and the release candidate is tagged. Barring any show-stopping issues, this is the final commit to be released on the 21st. https://gitlab.com/gitlab-org/security/gitlab/-/commits/18-3-stable-ee

Merge Requests that have been included in the monthly release will receive a label indicating inclusion.

Frequently Asked Questions

Who are the Release Managers for release X?

You can find this out by taking a look at the GitLab Release Managers schedule.

What is a release candidate and when are they created?

A release candidate (RC) is a GitLab package that includes the changes that will make it into the final monthly release, except for the rare case where a change may need to be reverted. RCs are only created for the monthly release, not patch releases. Usually, one RC is created per release, additional RCs can be created based on the state of Gitlab.com.

Release candidates are created in the run-up to the final release, two days before the release day. If necessary, release candidates can be created earlier if required. This will depend on factors such as:

• Any incidents on GitLab.com that are or have been going on in the run-up to the release.
• Any (critical) patch releases that require the attention of release managers.
• Any issues with our auto-deployment pipelines.
• Other release-related work that may delay or prevent the creation of a release candidate until said work is dealt with.

In other words, if you want to know when a release candidate is created your best option is to join one of the following Slack channels:

• #releases
• #f_upcoming_release

Release candidates are deployed to pre.gitlab.com for both automated and manual testing.

Will Release Managers create a release candidate earlier if I ask them to?

It is up to a Release Manager to decide when to create a release candidate, taking into account the state of deployments and GitLab.com.

Please do not message a Release Manager in private about release-related questions or requests. Instead, post your request/question in the #releases channel.

When do I need to have my MR merged in order for it to be included in the monthly release?

[!WARNING] ⚠️ The earlier in the monthly cycle your MR is merged, the higher the chances are for it to be included in that month’s release.

Target due date for including MRs in the monthly release: 16 UTC on the day before release procedures begin (typically 2 days before the release date).

The quality and stability of what is delivered by everyone define the final list of MRs that will be included in the monthly release. When GitLab.com is stable, MRs merged 2 days before release can be included. When stability is lower due to any team’s changes, even MRs merged 1 week before release may not make it.

Even if your MR deploys successfully before the due date, it may not be included in the release if:

• Any change on GitLab.com causes an incident or rollback
• GitLab.com experiences stability issues from other MRs
• A rollback occurs that reverts your changes along with problematic ones

For your MR to be included, it must be:

1. Merged to the default branch
2. Deployed successfully to GitLab.com production
3. Remain deployed without being rolled back

For real-time status of your MR, use the available tooling.

How can I get a high severity bug fix released?

Any high severity issue should start with an issue labeled with the appropriate bug and severity labels.

Depending on the bug details, follow one of the following processes:

• For high severity security bugs
• For high severity bugs affecting self-managed users. If the bug has been found close to the release date of the month, please also alert the Release Managers in #releases.
• For high severity bugs affecting GitLab.com
• For high severity bugs affecting security merge requests
• For high severity bugs affecting Dedicated

View page source - Edit this page - please contribute.