Before you upgrade

Before you upgrade, review the GitLab release and maintenance policy.

You should then create an upgrade plan that documents:

• The steps to take to upgrade your instance, including your upgrade path. Use the upgrade path tool to determine if your upgrade includes required upgrade stops. Upgrade stops might require you to perform multiple upgrades. If relevant, check OS compatibility with the target GitLab version.
• The steps to take if the upgrade doesn’t go smoothly.

Your upgrade plan should include:

• How to upgrade GitLab including, if possible and required, a zero-downtime upgrade.
• How to roll back GitLab, if necessary.

Pre-upgrade steps

Before you upgrade, you should:

1. Check for background 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.
2. Test your upgrade in a test environment first, and have a rollback plan to reduce the risk of unplanned outages and extended downtime.
3. Consult the GitLab upgrade notes for different versions of GitLab to ensure compatibility before upgrading.

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

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.