Gitlab migration to cloud instance


Iam looking to migrate my self-hosted GitLab to a cloud server and update it to the latest version, but I’m not sure what’s the most suitable approach:

  • Update GitLab from version 13.11.3-ee and follow the upgrade path to the latest version, then migrate GitLab to the cloud instance.
  • Migrate GitLab to cloud instance and then update it to the latest version.

Which seems more appropriate? Is the migration straightforward? (I also have some runners)

thank you for your help

This depends on a few things. Both ways are possible, it just depends on what Gitlab package versions are available. For example, if your self-hosted is Ubuntu 18.04, and your cloud instance is Ubuntu 22.04, then there might not even be Gitlab 13.x packages available for Ubuntu 22.04 to allow you to do that. In fact there aren’t, since the earliest Gitlab for Ubuntu 22.04 is a 15.x version.

It would help to know what operating system version you are using on your self hosted, and what version of operating system you plan to install on the cloud instance. Also, one other thing to note is which version of operating system to choose, because you can get more flexibility choosing one versus the other. I’ll give an example. If you choose an RHEL-based distro, these generally aren’t upgradeable between releases. Yes, there is leapp but it doesn’t always guarantee a clean upgrade from say RHEL8 to RHEL9, and even though Red Hat do have this tool, they still recommend a clean install. This with Gitlab then causes problems, since if the gap between RHEL8 and RHEL9 is too much, and a version of Gitlab doesn’t exist for it, than what exists on your RHEL8 install, then it makes the upgrade more difficult.

In comparision, if you chose or use Debian/Ubuntu, these are upgradeable between releases. My Gitlab server started back in 2017 most likely with Debian 9. It is now on Debian 12. I did not need to clean install it. And I’m currently on the latest 16.10.1 release. This makes it easier, especially if you’ve been upgrading regularly - I always check my server weekly and update every time a new version of a package comes out, including Gitlab. I don’t let my server lag in updates requiring me to then follow the upgrade path or potential operating system migration to get myself up-to-date.

My general recommendation, since I don’t know what operating system you are using right now, would be this. Install your cloud instance with an OS that can be upgraded, be it Debian or Ubuntu. It doesn’t matter if you are using RHEL/CentOS on your self hosted at this point (it is possible to restore a Gitlab backup on a different OS - I have restored my Debian Gitlab to a RHEL install of same Gitlab version). What does matter is that the version of Debian/Ubuntu you use has Gitlab 13.11.3-ee (a Gitlab backup can only be restored to the same version, eg: a backup of 13.11.3-ee can only be restored to 13.11.3-ee). Ubuntu 20.04 (focal) has this. Debian 10 (buster) also does. You can always upgrade the OS later from Ubuntu 20.04 to 22.04 once your Gitlab version on 20.04 is either at the latest version possible on that OS. At which point you upgrade to Ubuntu 22.04 and then continue the Gitlab upgrade process following the upgrade path. The same for Debian, you start with Debian 10, upgrade as far as you can go with Gitlab, then go to Debian 11, and repeat. Then do the same for Debian 12. If you get to Gitlab 16.10.1 on Debian 11 or Ubuntu 20.04, I would still recommend upgrading to Debian 12 or Ubuntu 22.04 at this point purely since both are pretty much end of life, or go end of life pretty soon.

Migrating is a case of:

  1. Take a backup of your self-hosted 13.11.3.
  2. Install Gitlab 13.11.3 on the cloud instance.
  3. Copy /etc/gitlab/gitlab.rb and /etc/gitlab/gitlab-secrets.json from self-hosted to cloud server.
  4. Run gitlab-ctl reconfigure.
  5. Copy the backup from self-hosted to cloud server.
  6. Run Gitlab restore procedures from the Gitlab documentation.

At this point you have migrated. Then it’s just a case of upgrading as per the Gitlab upgrade docs. If you have problems, you can revert to the self-hosted server since you haven’t lost it and haven’t attempted to upgrade it.

You could in theory upgrade the self-hosted as far as it can go first, before doing migration to cloud, but there is the extra risk if an upgrade fails. Then you would need to restore your self-hosted server. That is why I recommend not doing anything with the self-hosted server, and attempt to migrate as per the info above.

We can provide more specific information once we know more about your existing operating system and configuration. But other than that, the info above would still apply. How you go about it might chance slightly.

Remember, if you do look at upgrading your self-hosted first, always make sure you have a backup first, both using the Gitlab backup procedures, as well as a VM snapshot if you are using VM’s (that would in fact be quicker to revert to if the upgrade fails).

Some upgrade resources: GitLab Upgrade Path Resources


Before anything else, a huge thank you Ian for your in-depth answer, which is extremely interesting for me
To answer on the OS version, the self-hosted is a VM that run a Debian 10, and the cloud instance will be on Debian 12.

I fully understand your viewpoint of leaving the current server intact so that i can revert to it if needed, and the importance to proceed the migration before updating.

I will follow your advices, thank you again! :pray:

1 Like

If you have the possibility of installing the cloud instance with Debian 10, that would make things easier for you. You can always upgrade it through Debian 11 to 12 later.

If you install the cloud instance with Debian 12, it will make your migration harder. Or rather, you would need to upgrade your self-hosted to the latest Gitlab and then migrate. Which would then mean if something goes wrong with your self hosted instance, then you have neither.

I would install the cloud instance with Debian 10 and then install Gitlab 13.11.5 on it, take the backup from your self-hosted and restore it. Then I would upgrade Gitlab to the latest on Debian 10 which is 16.10.1.

At this point, I would upgrade the system to Debian 11. This will then you allow you to install Gitlab 16.10.1 over the buster version to get you on the Gitlab bullseye version. Then you upgrade to Debian 12, and upgrade to Gitlab 16.10.1 bookwork version.

If you can snapshot your self-hosted instance to make easier recovery if things go really wrong, then you can just upgrade self-hosted to the Gitlab 16.10.1 following the upgrade path, then take the backup and restore it in the cloud instance with Debian 12 and Gitlab 16.10.1.

1 Like

Indeed, thank you!

1 Like