Plan your upgrade path

Upgrading across multiple GitLab versions in one go is only possible by accepting downtime. If you don’t want any downtime, read how to upgrade with zero downtime.

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:

1. Upgrade to the required upgrade stop after your current version.
2. Allow the background migrations for the upgrade to finish.
3. Upgrade to the next required upgrade stop.

To provide a predictable upgrade schedule for instance administrators, from GitLab 17.5, required upgrade stops will occur at versions x.2.z, x.5.z, x.8.z, and x.11.z.

To determine your upgrade path:

1. Note where in the upgrade path your current version sits, including required upgrade stops:

   • GitLab 15 includes the following required upgrade stops:
     • 15.0.5.
     • 15.1.6. GitLab instances with multiple web nodes.
     • 15.4.6.
     • 15.11.13.
   • GitLab 16 includes the following required upgrade stops:
     • 16.0.10. Instances with lots of users or large pipeline variables history.
     • 16.1.8. Instances with NPM packages in their package registry.
     • 16.2.11. Instances with large pipeline variables history.
     • 16.3.9.
     • 16.7.10.
     • 16.11.10.
   • GitLab 17 includes the following required upgrade stops:
     • 17.1.8. Instances with large ci_pipeline_messages tables.
     • 17.3.7. The latest GitLab 17.3 release.
     • 17.5.z. The latest GitLab 17.5 release.
     • 17.8.z. The latest GitLab 17.8 release.
     • 17.11.z. The latest GitLab 17.11 release.

2. 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.

This includes major.minor versions you must stop at on the upgrade path because there may be fixes for issues relating to the upgrade process.

Specifically around a major version, crucial database schema and migration patches may be included in the latest patch releases.

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 even earlier versions of GitLab.

For example, the documentation for GitLab 15.11 contains information on versions back to GitLab 12.