Upgrade GitLab

Tier: Free, Premium, Ultimate Offering: Self-managed

Upgrading GitLab is a relatively straightforward process, but the complexity can increase based on:

  • The installation method you have used.
  • How old your GitLab version is.
  • If you’re upgrading to a major version.

Make sure to read the whole page as it contains information related to every upgrade method.

To upgrade GitLab:

  1. Familiarize yourself with the maintenance policy documentation.
  2. Read the release posts for versions you’re passing over. In particular, deprecations, removals, and important notes on upgrading.
  3. Check for background migrations.
  4. Plan your upgrade.
  5. Consult changes for different versions of GitLab to ensure compatibility before upgrading:
  6. Follow the upgrade steps based on your installation method.

Upgrade based on installation method

Depending on the installation method and your GitLab version, there are multiple official ways to upgrade GitLab:

Linux packages (Omnibus)

The package upgrade guide contains the steps needed to upgrade a package installed by official GitLab repositories.

There are also instructions when you want to upgrade to a specific version.

Helm chart (Kubernetes)

GitLab can be deployed into a Kubernetes cluster using Helm. For production deployments, the setup follows the Cloud Native Hybrid guidance where stateless components of cloud-native GitLab run in Kubernetes with the GitLab Helm chart, and stateful components are deployed in compute VMs with the Linux package.

Use the version mapping from the chart version to GitLab version to determine the upgrade path.

Follow Multi-node upgrades with downtime to perform the upgrade in a Cloud Native Hybrid setup.

A full cloud-native deployment is not supported for production. However, instructions on how to upgrade such an environment are in a separate document.

Docker

GitLab provides official Docker images for both Community and Enterprise editions, and they are based on the Omnibus package. See how to install GitLab using Docker.

Self-compiled (source)

In the past we used separate documents for the upgrading instructions, but we have switched to using a single document. The old upgrading guidelines can still be found in the Git repository:

Dealing with running CI/CD pipelines and jobs

If you upgrade your GitLab instance while the GitLab Runner is processing jobs, the trace updates fail. When GitLab is back online, the trace updates should self-heal. However, depending on the error, the GitLab Runner either retries, or eventually terminates, job handling.

As for the artifacts, the GitLab Runner attempts to upload them three times, after which the job eventually fails.

To address the above two scenarios, it is advised to do the following prior to upgrading:

  1. Plan your maintenance.

  2. Pause your runners, or block new jobs from starting by adding the following to your /etc/gitlab/gitlab.rb: 

    nginx['custom_gitlab_server_config'] = "location ^~ /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"

    And reconfigure GitLab with: 

    sudo gitlab-ctl reconfigure
  3. Wait until all jobs are finished.
  4. Upgrade GitLab.
  5. Upgrade GitLab Runner to the same version as your GitLab version. Both versions should be the same.
  6. Unpause your runners and unblock new jobs from starting by reverting the previous /etc/gitlab/gitlab.rb change.

Upgrading between editions

GitLab comes in two flavors: Community Edition which is MIT licensed, and Enterprise Edition which builds on top of the Community Edition and includes extra features mainly aimed at organizations with more than 100 users.

Below you can find some guides to help you change GitLab editions.

Community to Enterprise Edition

note
The following guides are for subscribers of the Enterprise Edition only.

If you wish to upgrade your GitLab installation from Community to Enterprise Edition, follow the guides below based on the installation method:

  • Source CE to EE upgrade guides - The steps are very similar to a version upgrade: stop the server, get the code, update configuration files for the new functionality, install libraries and do migrations, update the init script, start the application and check its status.
  • Omnibus CE to EE - Follow this guide to upgrade your Omnibus GitLab Community Edition to the Enterprise Edition.
  • Docker CE to EE - Follow this guide to upgrade your GitLab Community Edition container to an Enterprise Edition container.
  • Helm chart (Kubernetes) CE to EE - Follow this guide to upgrade your GitLab Community Edition Helm deployment to Enterprise Edition.

Enterprise to Community Edition

To downgrade your Enterprise Edition installation back to Community Edition, you can follow this guide to make the process as smooth as possible.