Upgrading a locally hosted GitLab instance can be a daunting task. Particularly if you have left it a few major versions. I recently decided to tackle my rather old installation, running 15.6.2. At the time, the latest version was 17.3.1 so two major versions behind.
Whatever you do, DO NOT just jump to the latest version, it will break and is not the recommended way to go about things.
Backup
The first thing to do is create BACKUPS. Backup everything. Export each repo into a tar.gz file in case anything goes horrifically wrong. You at least won’t lose your git repos.
Plan the Upgrade Path
Fortunately, the good people at GitLab have created a nice upgrade tool that advises of the various versions that need to be upgraded to in order to go from the version you are on to the version you want to upgrade to. In my case I was on 15.6.2 and wanted to go to the latest version 17.3.1. You can see the plan that was provided to me using this link.
The tool advised that I need to follow this path – 15.11.13 => 16.3.8 => 16.7.9 => 16.11.8 => 17.3.1
Pay particular notice to any warning notes detailing potential issues with the versions in-between the advised version steps in the upgrade path.
Download Images
The first thing to do is download all the required images. Container Manager -> Registry -> Search -> “gitlab/gitlab-ce” then download the specific images as detailed in the upgrade path from the GitLab upgrade tool. Once you have all of these downloaded, you can start upgrading your self-hosted GitLab instance.
Upgrade To A Different Image
The first thing to do is to Export the settings JSON settings file for your running GitLab instance. Container -> Action drop down -> Export -> Leave the Type as “Export Container Settings”
Save this file to your local machine.
Now, edit this JSON file and update two values. This is where your settings may differ from mine. But you want to update the name of the container it’s going to create to something relevant, or you could just edit this to be “gitlab-ce1” but the important setting is the image. This should be updated to use one of the images you downloaded previously and appears in the upgrade path also created previously using the GitLab tool.
Now stop your running container and then delete it. Don’t worry … it’s fine 🙂
Now to recreate that container using the exported JSON that defines the same container but with the updated image name.
Container -> Action drop down -> Import -> From local device -> Browse for the edited JSON file on your machine.
This will recreate the container but using the updated image. Now start this new container, Action drop down -> Start.
This will start the new container using the new image. The status indicator will go green at first. BUT, depending on the versions being upgraded to, there maybe a significant amount of migrating to do. In these cases, that status will go amber and Container Manager may say there are warnings. Don’t worry, this is the container doing upgrades and data migrations in the background.
Don’t expect to start this new container and be able to immediately navigate to your GitLab instance. It’ll take a while to start-up and work out what needs doing. Some of my upgrades took over 30 minutes. It will then start running the migrations and so on. You can watch this live by using the Terminal. Action drop down -> Open Terminal.
Once the status indicator goes back to Green, it’s most likely you can then navigate to your GitLab instance and see if the upgrade has worked. But beware, this isn’t always the end of the upgrade process. There may still be Background Migrations happening that absolutely need to complete before doing the next upgrade.
Once back in your GitLab instance, check for background migrations. Admin Area -> Monitoring -> Background Migrations
You need to allow these to all complete successfully before performing the next upgrade or stopping the container. These really need to complete.
Repeat this process for each step in your migration path and all should go well. I hope you’ve found this helpful, as it was really impossible to find a guide anywhere else.
Update Runners
Just for consistency, I also updated my various runners on Windows, MacOS and Linux.
Windows
Windows is pretty straightforward, stop the service, download the required binary (see the link above) possibly rename it based on how your service config is setup and then restart the service.
Linux
I’m running my Linux GitLab runner on a Ubuntu based Pop!_OS and so my upgrade process was the following commands:
sudo gitlab-runner stop
sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
sudo chmod +x /usr/local/bin/gitlab-runner
sudo gitlab-runner start
Upgrading a locally hosted GitLab instance can be a daunting task. Particularly if you have left it a few major versions. I recently decided to tackle my rather old installation, running 15.6.2. At the time, the latest version was 17.3.1 so two major versions behind.
Whatever you do, DO NOT just jump to the latest version, it will break and is not the recommended way to go about things.
Backup
The first thing to do is create BACKUPS. Backup everything. Export each repo into a tar.gz file in case anything goes horrifically wrong. You at least won’t lose your git repos.
Plan the Upgrade Path
Fortunately, the good people at GitLab have created a nice upgrade tool that advises of the various versions that need to be upgraded to in order to go from the version you are on to the version you want to upgrade to. In my case I was on 15.6.2 and wanted to go to the latest version 17.3.1. You can see the plan that was provided to me using this link.
The tool advised that I need to follow this path – 15.11.13 => 16.3.8 => 16.7.9 => 16.11.8 => 17.3.1
Pay particular notice to any warning notes detailing potential issues with the versions in-between the advised version steps in the upgrade path.
Download Images
The first thing to do is download all the required images. Container Manager -> Registry -> Search -> “gitlab/gitlab-ce” then download the specific images as detailed in the upgrade path from the GitLab upgrade tool. Once you have all of these downloaded, you can start upgrading your self-hosted GitLab instance.
Upgrade To A Different Image
The first thing to do is to Export the settings JSON settings file for your running GitLab instance. Container -> Action drop down -> Export -> Leave the Type as “Export Container Settings”
Save this file to your local machine.
Now, edit this JSON file and update two values. This is where your settings may differ from mine. But you want to update the name of the container it’s going to create to something relevant, or you could just edit this to be “gitlab-ce1” but the important setting is the image. This should be updated to use one of the images you downloaded previously and appears in the upgrade path also created previously using the GitLab tool.
Now stop your running container and then delete it. Don’t worry … it’s fine 🙂
Now to recreate that container using the exported JSON that defines the same container but with the updated image name.
Container -> Action drop down -> Import -> From local device -> Browse for the edited JSON file on your machine.
This will recreate the container but using the updated image. Now start this new container, Action drop down -> Start.
This will start the new container using the new image. The status indicator will go green at first. BUT, depending on the versions being upgraded to, there maybe a significant amount of migrating to do. In these cases, that status will go amber and Container Manager may say there are warnings. Don’t worry, this is the container doing upgrades and data migrations in the background.
Don’t expect to start this new container and be able to immediately navigate to your GitLab instance. It’ll take a while to start-up and work out what needs doing. Some of my upgrades took over 30 minutes. It will then start running the migrations and so on. You can watch this live by using the Terminal. Action drop down -> Open Terminal.
Once the status indicator goes back to Green, it’s most likely you can then navigate to your GitLab instance and see if the upgrade has worked. But beware, this isn’t always the end of the upgrade process. There may still be Background Migrations happening that absolutely need to complete before doing the next upgrade.
Once back in your GitLab instance, check for background migrations. Admin Area -> Monitoring -> Background Migrations
You need to allow these to all complete successfully before performing the next upgrade or stopping the container. These really need to complete.
Repeat this process for each step in your migration path and all should go well. I hope you’ve found this helpful, as it was really impossible to find a guide anywhere else.
Update Runners
Just for consistency, I also updated my various runners on Windows, MacOS and Linux.
Windows
Windows is pretty straightforward, stop the service, download the required binary (see the link above) possibly rename it based on how your service config is setup and then restart the service.
Linux
I’m running my Linux GitLab runner on a Ubuntu based Pop!_OS and so my upgrade process was the following commands: