info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
---
# Create a GitLab upgrade plan
This document serves as a guide to create a strong plan to upgrade a self-managed
GitLab instance.
General notes:
- If possible, we recommend you test out the upgrade in a test environment before
updating your production instance. Ideally, your test environment should mimic
your production environment as closely as possible.
- If [working with Support](https://about.gitlab.com/support/scheduling-live-upgrade-assistance.html)
to create your plan, share details of your architecture, including:
- How is GitLab installed?
- What is the operating system of the node?
(check [OS versions that are no longer supported](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html) to confirm that later updates are available).
- Is it a single-node or a multi-node setup? If multi-node, share any architectural details about each node with us.
- Are you using [GitLab Geo](../administration/geo/index.md)? If so, share any architectural details about each secondary node.
- What else might be unique or interesting in your setup that might be important for us to understand?
- Are you running into any known issues with your current version of GitLab?
## Pre-upgrade and post-upgrade checks
Immediately before and after the upgrade, perform the pre-upgrade and post-upgrade checks
to ensure the major components of GitLab are working:
1.[Check the general configuration](../administration/raketasks/maintenance.md#check-gitlab-configuration):
```shell
sudo gitlab-rake gitlab:check
```
1. Confirm that encrypted database values [can be decrypted](../administration/raketasks/doctor.md#verify-database-values-can-be-decrypted-using-the-current-secrets):
```shell
sudo gitlab-rake gitlab:doctor:secrets
```
1. In GitLab UI, check that:
- Users can log 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.
1. For GitLab CI/CD, check that:
- Runners pick up jobs.
- Docker images can be pushed and pulled from the registry.
1. If using Geo, run the relevant checks on the primary and each secondary:
```shell
sudo gitlab-rake gitlab:geo:check
```
1. If using Elasticsearch, verify that searches are successful.
If in any case something goes wrong, see [how to troubleshoot](#troubleshooting).
## 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.
### Back up GitLab
Create a backup of GitLab and all its data (database, repos, 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](../raketasks/backup_restore.md#back-up-gitlab).
Make sure to follow the instructions based on your installation method.
Don't forget to back up the [secrets and configuration files](../raketasks/backup_restore.md#storing-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
To restore your GitLab backup:
- Before restoring, make sure to read about the
[prerequisites](../raketasks/backup_restore.md#restore-gitlab), most importantly,
the versions of the backed up and the new GitLab istance must be the same.
-[Compiled from source](index.md#installation-from-source)
-[Docker](index.md#installation-using-docker)
-[Helm Charts](index.md#installation-using-helm)
-[Zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates)([if possible](index.md#upgrading-without-downtime) and desired)
-[Upgrade from GitLab Community Edition to Enterprise Edition, or vice-versa](https://docs.gitlab.com/omnibus/update/#upgrade-community-edition-to-enterprise-edition)
- What version should you upgrade to:
-[Determine what upgrade path](index.md#upgrade-paths) to follow.
- Account for any [version-specific update instructions](index.md#version-specific-upgrading-instructions).
- Account for any [version-specific changes](https://docs.gitlab.com/omnibus/update/#version-specific-changes).
- Check the [OS compatibility with the target GitLab version](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html).
- Due to [background migrations](https://docs.gitlab.com/omnibus/update/#background-migrations),
plan to pause any further upgrades after updating to a new major version.
[All migrations must finish running](index.md#checking-for-background-migrations-before-upgrading)
before the next upgrade.
- If available in your starting version, consider
[turning on maintenance mode](../administration/maintenance_mode/) during the
upgrade.
- About PostgreSQL:
- On the top bar, select **Menu > Admin**, and look for the version of
PostgreSQL you are using.
If [a PostgreSQL upgrade is needed](https://docs.gitlab.com/omnibus/package-information/postgresql_versions.html),
