GitLab Edition Upgrade Guide

Overview

This guide provides instructions for upgrading your self-hosted GitLab Community Edition (CE) instance. It is essential to follow the correct upgrade path, especially for minor version upgrades.

Prerequisites

• Ensure you have root or sudo access to the server.
• Backup your GitLab instance before performing an upgrade.
• Review the official GitLab upgrade documentation (opens in a new tab) for any specific release notes or breaking changes.

Step 1: Check Available Versions

To see the available versions of GitLab, use the following command:

sudo apt-cache madison gitlab-ee

This command will list all the versions available for installation.

Step 2: Upgrade GitLab

2.1 Upgrade Version by Version

To upgrade GitLab, you must follow the minor version upgrade path. For example, if you are upgrading from version 16.6.1 to 16.7.4, perform the following steps:

1. Update the package index:

   sudo apt update

2. Install the specific version of GitLab:

   sudo apt install gitlab-ee=16.7.4-ee.0

   Repeat this step for each minor version until you reach the desired version (e.g., upgrade from 16.6.1 to 16.7.4).

2.2 Upgrade to the Latest Version

If you want to upgrade to the latest version (e.g., 16.8.1), you can run:

sudo apt update
sudo apt install gitlab-ee

Alternatively, you can specify the exact version:

sudo apt install gitlab-ee=16.8.1-ee.0

Step 3: Restart and Reconfigure GitLab

After the upgrade, you need to restart and reconfigure GitLab:

1. Restart GitLab:

   sudo gitlab-ctl restart

2. Reconfigure GitLab:

   sudo gitlab-ctl reconfigure

Step 4: Verify the Upgrade

After the upgrade, verify that your GitLab instance is functioning correctly by performing the following tests:

• Clone an existing repository.
• Push changes to a repository.
• Create a new repository.
• Test the user interface (UI) by editing a file, merging branches, creating runners, and creating branches.

Important Notes

• Skipping Auto Backup (Not Recommended): If you need to skip the auto-backup during the upgrade for any reason, you can create a file:

  sudo touch /etc/gitlab/skip-auto-backup

• Backup Command: To create a backup manually, run:

  gitlab-backup create CRON=1

• Upgrade Path: Only minor versions should be upgraded one by one. For major version upgrades, refer to the specific upgrade instructions in the official documentation.

Conclusion

Following this guide will help you successfully upgrade your GitLab Community Edition instance while ensuring minimal disruption. For more detailed information and advanced configurations, refer to the GitLab documentation (opens in a new tab).