Before you upgrade

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

Before you upgrade, you should:

  1. Gather pre-upgrade information.
  2. Perform pre-upgrade steps.

Gather pre-upgrade information

When planning the upgrade, you should:

  1. Review the GitLab release and maintenance policy.

  2. Consult the GitLab upgrade notes for different versions of GitLab to ensure compatibility.

  3. If relevant, check OS compatibility with the target GitLab version.

  4. If you’re using Geo:

  5. Determine the appropriate upgrade path for your instance, including any required upgrade stops. Upgrade stops might require you to perform multiple upgrades.

  6. Create an upgrade plan that documents:

    • The steps to take to upgrade your instance including, if possible and required, a zero-downtime upgrade.
    • The steps to take if the upgrade doesn’t go smoothly including how to roll back GitLab if necessary.

With all pre-upgrade information gathered, you can move on to performing pre-upgrade steps.

Perform pre-upgrade steps

Soon before you perform the upgrade, you should:

  1. Test your upgrade in a test environment first to reduce the risk of unplanned outages and extended downtime.
  2. Run upgrade health checks.
  3. Perform upgrades for any optional features that you use.

Run upgrade health checks

Immediately before and after the upgrade, run upgrade health checks to ensure the major components of GitLab are working:

  1. Check the general configuration:

    sudo gitlab-rake gitlab:check

  2. Check the status of all background database migrations. All migrations must finish running before each upgrade. You must spread out upgrades between major and minor releases to allow time for background migrations to finish.

  3. Confirm that encrypted database values can be decrypted:

    sudo gitlab-rake gitlab:doctor:secrets

  4. In the GitLab UI, check that:

    • Users can sign in.
    • The project list is visible.
    • Project issues and merge requests are accessible.
    • Users can clone repositories from GitLab.
    • Users can push commits to GitLab.

  5. For GitLab CI/CD, check that:

    • Runners pick up jobs.
    • Docker images can be pushed and pulled from the registry.

  6. If using Geo, run the relevant checks on the primary site and each secondary site:

    sudo gitlab-rake gitlab:geo:check

  7. If using Elasticsearch, verify that searches are successful.

If something goes wrong, get support.

Upgrades for optional features

Depending on how your GitLab instance is configured, you might be required to perform these additional steps before upgrading GitLab:

  1. If using external Gitaly servers, upgrade the Gitaly servers to the newer version before upgrading GitLab itself. This prevents the gRPC client on the application server from sending RPCs that the old Gitaly version does not support.

  2. If you have Kubernetes clusters connected with GitLab, upgrade your GitLab agents for Kubernetes to match your new GitLab version.

  3. If you use advanced search (Elasticsearch), confirm advanced search migrations are complete by checking for pending migrations.

    After upgrading GitLab, you might have to upgrade Elasticsearch if the new version breaks compatibility. Updating Elasticsearch is out of scope for GitLab Support.

Working with Support

If you are working with Support to review your upgrade plan, document and share it with the answers to the following questions:

  • How is GitLab installed?
  • What is the operating system of the node? Check the supported platforms to confirm that later updates are available.
  • Is it a single-node or a multi-node setup? If multi-node, document and share any architectural details about each node. Which external components are used? For example, Gitaly, PostgreSQL, or Redis?
  • Are you using Geo? If so, document and share any architectural details about each secondary node.
  • What else might be unique or interesting in your setup that might be important?
  • Are you running into any known issues with your current version of GitLab?

Rollback plan

It’s possible that something may go wrong during an upgrade, so it’s critical that a rollback plan be present for that scenario. A proper rollback plan creates a clear path to bring the instance back to its last working state. It is comprised of a way to back up the instance and a way to restore it. You should test the rollback plan before you need it. For an overview of the steps required for rolling back, see roll back to earlier GitLab versions.

Back up GitLab

Create a backup of GitLab and all its data (database, repositories, uploads, builds, artifacts, LFS objects, registry, pages). This is vital for making it possible to roll back GitLab to a working state if there’s a problem with the upgrade:

  • Create a GitLab backup. Make sure to follow the instructions based on your installation method. Don’t forget to back up the secrets and configuration files.
  • Alternatively, create a snapshot of your instance. If this is a multi-node installation, you must snapshot every node. This process is out of scope for GitLab Support.

Restore GitLab

If you have a test environment that mimics your production one, you should test the restoration to ensure that everything works as you expect.

To restore your GitLab backup:

  • Before restoring, make sure to read about the prerequisites, most importantly, the versions of the backed up and the new GitLab instance must be the same.
  • Restore GitLab. Make sure to follow the instructions based on your installation method. Confirm that the secrets and configuration files are also restored.
  • If restoring from a snapshot, know the steps to do this. This process is out of scope for GitLab Support.