Skip to main content

GitLab: Metal EE to Turnkey EE

Objective

This guide covers the process of migrating to GitLab Enterprise Edition (EE) within a container environment, specifically using TurnKey Linux containers. We'll address how to properly restore a backup from another GitLab instance and upgrade to the latest version.

Background

When running GitLab in containerized environments, you can't modify the kernel directly. Using a pre-configured TurnKey instance that runs GitLab CE and upgrading it to EE is an efficient approach that avoids kernel modification issues.

Prerequisites

  • TurnKey GitLab container deployed in your virtualization platform
  • GitLab EE backup file from your source system
  • GitLab EE license

Step 1: Install GitLab EE with the Correct Version

First, determine the version of your backup:

# Backup filename format indicates version
# Example: 1745757520_2025_04_27_17.9.1-ee_gitlab_backup.tar

Install the matching GitLab EE version:

# Add the GitLab EE repository
curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

# Check available versions
apt-cache madison gitlab-ee

# Install the specific version matching your backup
sudo apt-get install gitlab-ee=17.9.1-ee.0  # Replace with your version

Step 2: Prepare and Restore the Backup

# Stop GitLab services that connect to the database
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq

# Create backup directory if it doesn't exist
sudo mkdir -p /var/opt/gitlab/backups

# Copy your backup file to the correct location
sudo cp your_backup_file.tar /var/opt/gitlab/backups/

# Set correct ownership
sudo chown git:git /var/opt/gitlab/backups/your_backup_file.tar

# Restore the backup
sudo gitlab-backup restore BACKUP=your_backup_timestamp_version

Step 3: Post-Restore Configuration

# Reconfigure and restart GitLab
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

# Verify all services are running
sudo gitlab-ctl status

Step 4: Update to the Latest GitLab EE Version

To properly update GitLab to the latest version, follow these steps to fix repository configuration issues:

1. Complete Repository Reset

Remove all conflicting and outdated GitLab repository configurations:

sudo rm -f /etc/apt/sources.list.d/gitlab*
sudo rm -f /etc/apt/preferences.d/gitlab*
sudo rm -f /usr/share/keyrings/gitlab*

2. Proper GPG Key Installation

Install the GPG key correctly using the modern method:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://packages.gitlab.com/gitlab/gitlab-ee/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/gitlab-ee-archive-keyring.gpg

3. Modern Repository Configuration

Use the newer signed-by syntax which explicitly links the repository to its key:

echo "deb [signed-by=/etc/apt/keyrings/gitlab-ee-archive-keyring.gpg] https://packages.gitlab.com/gitlab/gitlab-ee/debian bookworm main" | sudo tee /etc/apt/sources.list.d/gitlab_ee.list

4. Update and Install Latest Version

With proper configuration in place, update without version pinning:

sudo apt-get update
sudo apt-get install gitlab-ee
sudo gitlab-ctl reconfigure

Troubleshooting Guide

Issue: Version Mismatch During Restore

If the restore fails with a version mismatch error, make sure to install the exact GitLab version from the backup first, then upgrade after a successful restore.

Issue: GitLab Not Updating to Latest Version

If GitLab remains at the old version after trying to update, the issue is typically related to:

  • Conflicting repository configurations
  • Authentication problems with the repository
  • Hidden preferences pinning to the old version

Follow the complete repository reset procedure in Step 4 to resolve these issues.

Issue: Repository Signing Error

If you see GPG key errors when updating packages, follow the GPG key installation in Step 4 to properly configure the signing key.

Best Practices

  1. Always match the GitLab version to your backup version during restoration
  2. Perform a complete system backup before attempting any upgrade
  3. Verify successful restoration before upgrading to the latest version
  4. Set up proper repository configurations to enable seamless future updates

Why This Approach Works

Using this method ensures that your GitLab instance is properly restored with all user data, repositories, and settings intact, while avoiding kernel modification issues common in containerized environments. The proper repository setup ensures you can easily update to newer versions as they become available.

Back to top