GitLab Upgrade Cookbook From 16.1.1 to 17.9.2

After the GitLab recovery, we still have to keep our GitLab up to date. This article will explain the upgrade steps for GitLab from GitLab version 16.1.1.

Prerequisites

It is assumed that you already have GitLab installed, if not have a look here (wiki.mphslaats.com).

This article explains upgrade steps from GitLab 16.6.1 onwards, these are the upgrade steps I have taken. In case you are on a different version please consult the GitLab help pages for more information. If you want older upgrade versions have a look here (wiki.mphslaats.com).

When upgrading GitLab check the GitLab changelog at gitlab.com and the migration guide at docs.gitlab.com.
If you don’t like reading you can use the GitLab Upgrade Path Tool (gitlab-com.gitlab.io).

Upgrading GitLab

Updating GitLab and saving the output to a log file for further analysis is recommended. This can be done as follows:

# Update to latest version
apt-get update && apt-get dist-upgrade 2>&1 | tee YYYYMMMDD_xx_update.log
# Update to a specific version
VERSION=x.x.x
apt-get install gitlab-ce=$VERSION-ce.0 2>&1 | tee YYYYMMMDD_xx_gitlab-ce_$VERSION-ce.0.log

Do not forget to check the Background Migrations tasks at /admin/background_migrations or go via Admin Area > Monitoring > Background Migrations.

Upgrade to 17.9.2

When upgrading from GitLab 17.8.x to 17.9.2, no extra steps are needed if you take the required stops.

Upgrade to 17.8.1

When upgrading from GitLab 17.7.x to 17.8.1, no extra steps are needed if you take the required stops.

Upgrade to 17.7.0

When upgrading from GitLab 17.5.x to 17.7.0, no extra steps are needed if you take the required stops.

Upgrade to 17.5.0

When you upgrade from GitLab 17.3.0, you must stop at 17.5.x. After installing it, no extra steps were needed.

Upgrade to 17.3.0

When you upgrade from GitLab 16.11.0, you must stop at 17.3.x. After installing it, no extra steps were needed.

Upgrade to 16.11.0

When you upgrade from GitLab 16.10.1, you must stop at 16.11.x. After installing it, no extra steps were needed.

Upgrade to 16.10.1

When upgrading from GitLab 16.7.0 to 16.10.1, the GPG key expired, therefore, follow the steps in this article (docs.gitlab.com). In my scenario, I had to run:

 awk '/deb \[signed-by=/{
       pubkey = $2;
       sub(/\[signed-by=/, "", pubkey);
       sub(/\]$/, "", pubkey);
       print pubkey
     }' /etc/apt/sources.list.d/gitlab_gitlab-?e.list | \
   while read line; do
     curl -s "https://packages.gitlab.com/gpg.key" | gpg --dearmor > $line
   done

Upgrade to 16.7.0

When upgrading from GitLab 16.6.1 to 16.7.0, the default PostgreSQL database changed from 13 to 14. This is still an optional update since it is not supported yet for Geo installations (docs.gitlab.com). If you want to update to PostgreSQL 14 for your GitLab you will have to do it manually as described below.

To upgrade your PostgreSQL to the version packaged in GitLab run the command below (docs.gitlab.com). In case you want to upgrade to a specific version add -V __VERSION__.

gitlab-ctl pg-upgrade 2>&1 | tee YYYYMMMDD_xx_pg-upgrade.log

After the upgrade validate if GitLab works and all the data is in place. If so remove the upgrade files using:

rm -rf /var/opt/gitlab/postgresql/data.13
rm -f /var/opt/gitlab/postgresql-version.old

Upgrade to GitLab 16.6.1

When you upgrade from GitLab 16.1.1 you need to make a stop at 16.3.x to perform a database analysis before continuing the upgrade (docs.gitlab.com). Make the stop by running:

apt-get install gitlab-ce=16.3.6-ce.0 2>&1 | tee YYYYMMMDD_xx_gitlab-ce_16.3.6-ce.0.log

Now connect to the database using gitlab-rails dbconsole and execute the following:

ANALYZE packages_packages;

If no errors are shown, you can safely continue upgrading GitLab.