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:
(check [OS versions that are no longer supported](../administration/package_information/deprecated_os.md) 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: