Gitlab Upgrade Plan

This document covers all the necessary steps to ensure a smooth and safe upgrade of Gitlab from version 14.8 to the latest 17.8 release with best efforts to minimize downtime.

Pre-Requisites

1. Take a note of the exact Docker Image Version before upgrade
2. Backup the Instance Credentials gitlab.rb, gitlab-secrets.json ¹
3. Stop the running Instance and perform a complete backup using the STRATEGY=copy option ^{2 3}

Upgrade Strategy

Plan A - (Onsite Upgrade)

This plan explores the upgrade path where we upgrade the version of GitLab on the current running Instance

OnSite Gitlab Upgrade

+−⟲

Link to original

Plan B - (Offsite Upgrade)

OffSite Gitlab Upgrade

+−⟲

Link to original

GITLAB Instance will not be available for the users during the migration/upgrade activity

Upgrade Process

1. Refer to Gitlab Update Documentation for complete information on the upgrade process
2. Refer to Gitlab Upgrade Paths for the recommended upgrade stops
3. Refer to Gitlab Upgrade Path Tool for upgrade from v14.8 -> v17.8 ⁴
4. Refer to Gitlab Docker Installation Upgrade for the official recommended upgrade process
5. As we change the Gitlab Version in the Docker image, the container automatically detects and performs the upgrade activity ⁵

Rollback Plan

As mentioned in the Pre-Requisites we have a backup that corresponds to the source version, we start the Gitlab instance with the source version and restore the backup, Refer to Gitlab Documentation - Restore GitLab and perform the Gitlab Instance restore for the current installation, by stopping the background services Puma and Sidekiq and then perform the restoration using the gitlab-backup utility ⁶

It is necessary that we perform a POC to validate the above and processes

The Gitlab Runner Major Release Version should match the Gitlab Instance Major Release version ¹

Footnotes

1. Gitlab Documentation- Storing Configuration Files ↩

2. Gitlab Documentation - Backup Strategy Options ↩

3. Back up GitLab running in a Docker container ↩

4. Gitlab Upgrade Path Toolbox ↩

5. Upgrade GitLab using Docker Engine ↩

6. Restore for Docker image installations ↩