Roll back to earlier GitLab versions

You can roll back to earlier versions of GitLab instances that were installed by using the Linux package or Docker.

When rolling back, you must take into account version-specific changes that occurred when you previously upgraded.

Prerequisites

Because you must revert the database schema changes (migrations) that were made when the instance was upgraded, you must have:

• At least a database backup created under the exact same version and edition you are rolling back to.
• Ideally, a full backup archive of that exact same version and edition you are rolling back to.

Roll back a Linux package instance

To roll back a Linux package instance to an earlier GitLab version:

1. Stop GitLab and remove the current package:

   # If running Puma
   sudo gitlab-ctl stop puma
   
   # Stop sidekiq
   sudo gitlab-ctl stop sidekiq
   
   # If on Ubuntu: remove the current package
   sudo dpkg -r gitlab-ee
   
   # If on Centos: remove the current package
   sudo yum remove gitlab-ee

2. Identify the GitLab version you want to roll back to:

   # (Replace with gitlab-ce if you have GitLab FOSS installed)
   
   # Ubuntu
   sudo apt-cache madison gitlab-ee
   
   # CentOS:
   sudo yum --showduplicates list gitlab-ee

3. Roll back GitLab to the desired version (for example, to GitLab 15.0.5):

   # (Replace with gitlab-ce if you have GitLab FOSS installed)
   
   # Ubuntu
   sudo apt install gitlab-ee=15.0.5-ee.0
   
   # CentOS:
   sudo yum install gitlab-ee-15.0.5-ee.0.el8

4. Reconfigure GitLab:

   sudo gitlab-ctl reconfigure

5. Restore GitLab to complete the roll back.

Roll back a Docker instance

The restore overwrites all newer GitLab database content with the older state. A rollback is only recommended where necessary. For example, if post-upgrade tests reveal problems that cannot be resolved quickly.

To roll back GitLab shortly after an upgrade:

1. Follow the upgrade procedure, by specifying an earlier version than you have installed.

2. Restore the database backup you made before the upgrade.

   • Follow the restore steps for Docker images, including stopping Puma and Sidekiq. Only the database must be restored, so add SKIP=artifacts,repositories,registry,uploads,builds,pages,lfs,packages,terraform_state to the gitlab-backup restore command line arguments.