Upgrading your GitLab instance is essential to leverage new features, security patches, and performance improvements. In this comprehensive guide, we’ll walk you through the easiest and most secure way to upgrade your Omnibus GitLab installation on a Linux system.

Introduction

GitLab is a powerful web-based Git repository manager that offers extensive features for code collaboration, version control, and continuous integration/continuous delivery (CI/CD). The Omnibus GitLab package simplifies the installation and management process by bundling GitLab with all its dependencies.

Upgrading GitLab might seem daunting, especially if you’re new to system administration. However, with the right steps, you can perform the upgrade smoothly and securely. This guide is designed to help you upgrade your GitLab Omnibus installation step-by-step, ensuring minimal downtime and data integrity.

Table of Contents

Before You Begin

Before starting the upgrade process, ensure you have:

  • Root or Sudo Access: You need administrative privileges to perform the upgrade.
  • Current GitLab Version Information: Know your existing GitLab version.
  • Desired Upgrade Version: Determine the GitLab version you want to upgrade to.
  • Backup Plan: Always back up your data before making significant changes.

Step 1: Check Current GitLab Version

First, find out which version of GitLab you are currently running. You can do this by accessing your GitLab instance’s help page or via the command line.

Option 1: Through the Web Interface

Navigate to:

http://your-gitlab-url/help

You’ll see the version number at the top of the page.

Option 2: Via Command Line

Run the following command on your GitLab server:

bash
sudo gitlab-rake gitlab:env:info

This will display detailed information about your GitLab environment, including the version.

Step 2: Determine the Upgrade Path

Upgrading GitLab often requires stepping through intermediate versions, especially if you’re several versions behind. Use the GitLab Upgrade Path Tool to determine the correct upgrade path:

GitLab Upgrade Path Tool

Enter your current version and the target version to get a tailored upgrade path.

Step 3: Backup Your GitLab Data

Important: Always back up your data before upgrading.

Create a Backup of GitLab Data

Run the following command to create a backup of your GitLab repositories, uploads, and more:

bash
sudo gitlab-backup create

Backup Configuration Files

The backup command does not include your configuration files. Manually back up the following files:

  • GitLab Secrets:

    bash
    sudo cp /etc/gitlab/gitlab-secrets.json /backup/location/gitlab-secrets.json

  • GitLab Configuration:

    bash
    sudo cp /etc/gitlab/gitlab.rb /backup/location/gitlab.rb

Replace /backup/location/ with your desired backup directory.

Step 4: Update GitLab Package Repository

Ensure your system is set up to receive GitLab package updates.

bash
curl -s https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

This script adds the GitLab package repository to your system.

Step 5: Perform the Upgrade

Using the version information from the Upgrade Path Tool, run the appropriate command to upgrade to the next version in your upgrade path.

bash
sudo apt-get install -y gitlab-ce=15.2.5-ce.0

Replace 15.2.5-ce.0 with the version number specified in your upgrade path.

Note: The package name might be gitlab-ce for the Community Edition or gitlab-ee for the Enterprise Edition.

Wait for the Upgrade to Complete

The upgrade process may take some time. Do not interrupt it. Once completed, you should see a success message.

Step 6: Restart GitLab Services

After upgrading, restart GitLab services to ensure all components are running the new version.

bash
sudo gitlab-ctl restart

Step 7: Verify the Upgrade

Check GitLab Version

Visit your GitLab instance’s help page to confirm the new version:

http://your-gitlab-url/help

Run a System Check

Perform a health check to ensure all components are functioning correctly:

bash
sudo gitlab-rake gitlab:check

Review the output for any errors or warnings.

Verify Database Migrations

Ensure all database migrations have been applied:

bash
sudo gitlab-rake db:migrate:status

All migrations should have a status of up.

Check Background Migrations

Background migrations may take additional time. Check their status:

  1. Log in to GitLab as an administrator.
  2. Navigate to Admin Area > Monitoring > Background Migrations.
  3. Ensure all migrations have a status of Finished.

Verify Running Processes

Check that all GitLab components are running:

bash
sudo gitlab-ctl status

You should see that all services are running.

Conclusion

Congratulations! You’ve successfully upgraded your Omnibus GitLab installation. Regularly updating GitLab ensures you have the latest features, security updates, and performance improvements.

If you have any questions or need further assistance, feel free to reach out to us at support.tools.

References