This page describes the processes used to release packages to self-managed users.
Monthly self-managed release
GitLab version (XX.YY.0) is published every month. 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 release date.
Overview of the steps involved on the self-managed release process:
The end-to-end process consists on the following stages:
The only guaranteed date throughout the release cycle is the release date. 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 release date, 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 release date. https://gitlab.com/gitlab-org/gitlab/commits/4033cb0ed66de77a4b5c1936e33de918edef558e
The last commit to make it into the release will have a message similar to this:
📣 Barring any show-stopping issues, this is the final commit to be released on the release date. 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.
GitLab team members can view the internal Grafana dashboard “Release Information” for the following information:
The metrics used to display this information are updated automatically throughout the self-managed releases process.
The patch release policy allows bug fixes to be backported to the current stable released version of GitLab. 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).
Patch releases are scheduled twice a month on the second and fourth Wednesdays, around the monthly release week. These are best-effort dates and they might be subject to change.
Patches fix regressions in the current self-managed release.
If you’re a GitLab engineer looking to include a bug fix in a release, please follow the steps on the patch release runbook for GitLab engineers.
Overview of the steps involved with creating a patch release:
The end-to-end process consists on the following stages:
Details of the patch release lifecycle can be found on the patch release documentation, including the patch release runbook for GitLab engineers and the patch release runbook for release managers.
The security release processes are used to prepare and publish packages containing vulnerability fixes. For more details about the release overview and the release processes, see the security release page.
For information on backports, visit the backports page.
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 2 days before the release date were included in the release. On the opposite side, when GitLab.com stability was lower, MR’s merged as early as one week before the release date 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 information:
The different processes are documented here:
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:
| 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.
1673d31a)
