Plan your upgrade path
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
An upgrade path involves steps to move from your current GitLab version to the GitLab version you want to upgrade to. To determine your upgrade path:
- Note where in the upgrade path your current version sits, including required upgrade stops.
- Consult the GitLab upgrade notes.
Even when not explicitly specified, upgrade GitLab to the latest available patch release of the major.minor release
rather than the first patch release. For example, 16.8.7 instead of 16.8.0.
Some major.minor versions are required stops for some or all environments because there are
fixes for issues relating to the upgrade process.
Required upgrade stops
Upgrade paths include required upgrade stops, which are versions of GitLab that you must upgrade to before upgrading to later versions. When moving through an upgrade path:
- Upgrade to the required upgrade stop after your current version.
- Allow the background migrations for the upgrade to finish.
- Upgrade to the next required upgrade stop.
In GitLab 17.5 and later, to provide a predictable upgrade schedule for instance administrators, required upgrade stops occur
at versions x.2.z, x.5.z, x.8.z, and x.11.z.
To check available patch releases for a specific minor version, you can search for the minor version in the GitLab package repository. For example, to search for the latest GitLab 18.2 Enterprise Edition version, go to https://packages.gitlab.com/app/gitlab/gitlab-ee/search?q=18.2.
If you’re upgrading a GitLab Helm chart instance, see the list of GitLab Helm chart mappings.
Required GitLab 17 upgrade stops
You must upgrade to these versions of GitLab 17 before upgrading to later versions.
| Required version | Notes |
|---|---|
| 17.11.7 | Upgrade to the latest GitLab 17.11 patch release. See upgrade notes for GitLab 17.11.0. |
| 17.8.7 | Upgrade to the latest GitLab 17.8 patch release. See upgrade notes for GitLab 17.8.0. |
| 17.5.5 | Upgrade to the latest GitLab 17.5 patch release. See upgrade notes for GitLab 17.5.0. |
| 17.3.7 | Upgrade to the latest GitLab 17.3 release. See upgrade notes for GitLab 17.3.0. |
| 17.1.8 | Required only for instances with large ci_pipeline_messages tables. See upgrade notes for GitLab 17.1.0. |
Required GitLab 16 upgrade stops
You must upgrade to these versions of GitLab 16 before upgrading to later versions.
| Required version | Notes |
|---|---|
| 16.11.10 | See upgrade notes for GitLab 16.11.0. |
| 16.7.10 | See upgrade notes for GitLab 16.8.0 and later GitLab 16.7 versions. |
| 16.3.9 | See upgrade notes for GitLab 16.3.0 and later GitLab 16.3 versions. |
| 16.2.11 | Required only for GitLab instances with large pipeline variables history. See upgrade notes for GitLab 16.2.0. |
| 16.1.8 | Required only for GitLab instances with NPM packages in their package registry. See upgrade notes for GitLab 16.1.0. |
| 16.0.10 | Required only for GitLab instances with lots of users or large pipeline variables history. See upgrade notes for GitLab 16.0.0 and later GitLab 16.0 versions. |
Required GitLab 15 upgrade stops
You must upgrade to these versions of GitLab 15 before upgrading to later versions.
| Required version | Notes |
|---|---|
| 15.11.13 | See upgrade notes for GitLab 15.11.0 and later GitLab 15.11 versions. |
| 15.4.6 | See upgrade notes for GitLab 15.4.0 and later GitLab 15.4 versions. |
| 15.1.6 | Required only for GitLab instances with multiple web nodes. See upgrade notes for GitLab 15.1.0. |
| 15.0.5 | See upgrade notes for GitLab 15.0. |
Upgrade Path tool
To quickly calculate which upgrade stops are required based on your current and desired target GitLab version, see the Upgrade Path tool. This tool is maintained by the GitLab Support team.
To share feedback and help improve the tool, create an issue or merge request in the
upgrade-path project.
Earlier GitLab versions
For information on upgrading to earlier GitLab versions, see the documentation archives. The versions of the documentation in the archives contain version-specific information for earlier versions of GitLab.