This page describes the processes used to release packages to self-managed users.
The Monthly self-managed release: GitLab version (XX.YY.0) is published every month on the 22nd. From this monthly release, patch, non-critical, and critical security releases are created as needed.
Our maintenance policy describes in detail the cadence of our major, minor and patch releases for self-managed users. The major release yearly cadence was defined after an all stakeholder discussion.
The self-managed 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.
The monthly self-managed release timelines are concentrated around the 22nd.
Monthly self-managed release preparation steps
12-3-stable and a test release candidate (RC) is tagged. The test RC checks that a package can be built and successfully deployed and tested on the Pre environment. At this point release managers will announce the final commit to be included in the releaseThe only guaranteed date throughout the release cycle is the 22nd. On this date,
the self-managed 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 self-managed release.
When we create release candidates, and when we create a new release package, the Release Tools project will add a label to the merge requests included.
For more information, refer to the Auto-deploy status command.
In the runup to the 22nd, release managers will also start announcing what commit will at the very least 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):
This is the candidate commit to be released on the 22nd. https://gitlab.com/gitlab-org/gitlab/commits/4033cb0ed66de77a4b5c1936e33de918edef558e
The last commit to make it into the release will have a message similar to this:
:mega: Barring any show-stopping issues, this is the final commit to be released on the 22nd. https://gitlab.com/gitlab-org/gitlab/-/commits/13-1-stable-ee
Merge Requests that have been included in the monthly release will receive a label indicating inclusion.
The patch release policy allows bug fixes to be backported to the current stable released version of GitLab. Patches are created on demand according to our maintenance policy and at the discretion of release managers. Patches that are outside of our maintenance policy for bug fixes must be requested and agreed upon by the release managers and the requester (see backporting to versions outside the maintenance policy for details).
Patches are released on an as-needed basis in order to fix regressions in the current self-managed release. The end-to-end process consists on the following stages:
Details of steps 1 to 3 can be found on the patch release runbook for GitLab engineers while details for steps 4 to 7 can be found on the patch release runbook for release managers.
The release process has a few labels of specific importance.
Incidents may optionally have a Delivery impact:* label to indicate the impact the incident has when active. This label is intended to help with prioritizing between multiple incidents.
| Impact label | Definition |
|---|---|
| Delivery impact::1 | Deployments and/or scheduled releases are fully blocked by this incident. Action should be taken to resolve this immediately |
| Delivery impact::2 | Deployments and/or scheduled releases will soon become blocked. Resolve as soon as possible |
| Delivery impact::3 | Deployments and releases are not currently blocked but there is some impact on the delivery process |
As a merge request is included in monthly self-managed release candidates (RC), it will receive the
released::candidate label when the release candidate it is included in is deployed to
[pre.gitlab.com]. See "What is a release candidate and when are they created?"
for more information on release candidates. This label indicates that the MR will most
likely be included in the upcoming Self-managed release.
A merge request will receive the released::published label (which replaces the released::candidate label)
when included in a packaged release, such as 13.6.0 or 13.5.2, and deployed to
release.gitlab.net for both automated and manual testing. This label indicates that the
MR will be published with the Self-managed release.
You can find this out by taking a look at the GitLab Release Managers schedule.
A release candidate (RC) is a GitLab package that includes the changes that will make it into the final self-managed release, except for the rare case where a change may need to be reverted. RCs are only created for the monthly self-managed release, not patch releases. The amount of RCs created per month will vary per release.
There is no fixed point in time where a release manager creates a release candidate. Instead, this is based entirely on how the release process has been going, what the state is of GitLab.com, etc.
Release candidates are created whenever possible, and as such there are no guarantees on creation timing. This will depend on factors such as:
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:
Release candidates are deployed to [pre.gitlab.com] for both automated and manual testing.
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.
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.
There is no guaranteed "cut-off", "freeze" or any other date defined under which the MR will be included.
Availability, security and performance of GitLab.com is a pre-requisite for any monthly self-managed release. If GitLab.com is not experiencing any issues, MR's merged as late as the 20th of the month were included in the release. On the opposite side, when GitLab.com stability was lower, MR's merged as early as 15th of the month were not included.
In other words:
The quality and stability of what is delivered by everyone defines the final MR that will be included in the monthly release.
For more detailed answer, see self-managed release timelines.
The different processes are documented here:
See the Security Release process as Developer documentation for more information.
Also, make sure to see Security Releases How to video for a broad explanation about all the steps required as a Developer when working on a security fix.
Security issues created on GitLab Security need to be associated with the Security Release Tracking issue for them to be included on the Security Release. Make sure to use the security issue template and follow the steps there.
Besides the merge request targeting master, three backports will be needed targeting the last two monthly releases and the current release.
For more information, see security release backports.
Any high severity issue should start with an issue labelled with the appropriate bug and severity labels.
Depending on the bug details, follow one of the following processes:
Once a security merge request has been merged, it's not advisable to revert it for multiple reasons:
If a security vulnerability introduced a bug, in most cases, the appropriate path forward is to fix the issue in the canonical repository (after the security release has been published).
If a security vulnerability introduced a high severity bug, engage with AppSec and release managers to coordinate next steps.
| Description | Location |
|---|---|
| Release documentation | Link |
| Issue Tracker | gitlab-org/release/tasks |
| Slack Channels | #f_upcoming_release / @release-managers |
| Release Manager schedule | Link |
| Maintenance Policy | Link |
| Reaching us | How to find us |
If you need any additional help please ask the Release Managers in the #releases Slack channel.