How to Mirror Your On-Premises GitLab Repo to GitLab Cloud for Resiliency

I use Gitlab extensively in the home lab for various purposes and running my CI/CD pipelines. Even though I back up my Gitlab environment and container data, I still want to make sure that I have things configured in a way where if things “hit the fan”, I can still have confidence that my Gitlab repos are safe. If I have a hardware failure, network outage, or even larger disaster, mirroring your Gitlab repositories from an on-premise repo to a cloud-hosted Gitlab instance is a good way to have yet another copy of your data. Let’s look at the step-by-step instructions to set up repository mirroring from your self-hosted GitLab server to GitLab cloud.

Why mirror your GitLab repository?

We have already touched on this in the introduction. However, what are the reasons we might mirror repos in GitLab on-premises repos up to the cloud version of Gitlab?

Note the following reasons that I can think of:

• Disaster Recovery: A cloud mirror helps to protect against data loss and hardware failures
• High Availability: Makes sure that you can always access your code, even if your local instance is down
• Backup and Redundancy: Automatic backups and replication reduce risk of data loss

I sleep better at night knowing that all the local development that I have done for my home lab is mirrored at another location.

Prerequisites to setting this up

Before setting up mirroring, you need to make sure you have:

• Admin or Maintainer access to your on-premises GitLab repository
• A GitLab.com account and a new empty repository created in GitLab Cloud
• Network connectivity between your on-premises server and GitLab Cloud
• Ability to unprotect a branch on your cloud instance

Step-by-Step Guide to Mirror Your GitLab Repo

There aren’t many steps to get this setup and it isn’t that challenging, so let’s take a look at how to do this in the next few steps.

Step 1: Create a New GitLab Repository in the Cloud

• Log in to GitLab.com.
• Click New project and select Create blank project.
• Enter your project details and create the repository.

Below we see the New project button. Click this to get started creating the new project.

I chose to create a blank project which is easiest.

Fill in the details of your project, including the project name, slug (automatically generated but you can customize), etc. Then click Create Project.

Step 2: Unprotect the repo

In my testing, you have to unprotect the protected branch and allow force push for this to work. However, this feels like a sledgehammer approach and there may be settings elsewhere to allow this push to work from on-premises without this, but here are the steps to do that.

Step 3: Get the Mirroring URL

Once your GitLab Cloud repo is set up:

• Navigate to your new GitLab Cloud repository.
• Click the Code button and copy the HTTPS or SSH URL

Step 4: Set Up Repository Mirroring on Your On-Premises GitLab

Now, we move on to the on-premises GitLab server. We will now setup our on-premises repository to mirror to the cloud GitLab instance.

On your on-premises GitLab server, you will follow the following workflow:

• Open your repository.
• Navigate to Settings → Repository.
• Scroll down to Mirroring repositories.
• Enter the GitLab Cloud repository URL you copied earlier into the “Git repository URL” box
• Provide your credentials

Click your Repository settings.

Click on the Add new button under the Mirroring repositories.

Here, you will need to enter the Git repository URL from your GitLab cloud instance you setup. Then your Authentication method. Then click Mirror repository.

Forcing your first update

If you don’t want to wait for the automatic push to happen, which I believe is every 5 minutes, you can force the update.

Choosing your mirroring direction

You have two types of mirroring directions. Since in my case and I think most home labs, if you have an on-premises GitLab instance, this will be the master or source of truth. You will want to use push mirroring. However, note the difference below.

• Push Mirroring: Sends changes from your on-premises repo to GitLab Cloud
• Pull Mirroring: Pulls changes from the GitLab Cloud repo to your on-premises installation.

For resiliency and disaster recovery, select Push Mirroring.

• Choose Push as the mirroring type.
• Ensure the option “Mirror repository” is checked.

Verify Mirroring Setup

Once set up, your repository mirroring will initiate automatically:

• Check the “Mirroring repositories” section for status
• Ensure it reads “Last successful update”
• Perform test commits locally and push to your on-premises GitLab repository
• Verify these changes appear promptly on your GitLab Cloud repo

You should be able to see after a few moments that your cloud GitLab repo will populate with the same resources as your on-premises GitLab repository. Also, the commit hash should be identical once the synchronization happens.

Troubleshooting Common Issues

If you encounter issues:

• Authentication Failures: Ensure the token is valid and has proper permissions.
• Network Errors: Verify firewall settings and network connectivity.
• Delayed Syncs: Check if auto-sync frequency settings are configured correctly.

Mirroring Multiple Repositories

If you have many repositories that you are managing, mirroring configuration manually might be a chore. You can use GitLab APIs or scripting. Unfortunately, there isn’t a global mirror all repositories or something of that nature. However, again, you can script this out between your on-premises repo and the cloud.

Securing Your Mirrored Repositories

Always follow best security practices:

• Regularly rotate access tokens.
• Limit token permissions to the necessary minimum.
• Monitor audit logs regularly.

Wrapping up

I really like the idea, especially as you get more into DevOps with your self-hosted GitLab instance to mirror the repositories you have as it is just another way to protect all the hard work you have put into your code repos and getting things working. I would hate to know I lost many hours of work on getting a process scripted or automated in the home lab due to losing my self-hosted GitLab instance. Let me know in the comments. Are you doing this as well in your home lab, production, etc?