Install GitLab using the Linux package

The Linux packages are mature, scalable, and are used on GitLab.com. If you need additional flexibility and resilience, we recommend deploying GitLab as described in the reference architecture documentation.

The Linux package is quicker to install, easier to upgrade, and contains features to enhance reliability not found in other installation methods. Install through a single package (also known as Omnibus GitLab) that bundles all the different services and tools required to run GitLab. See the installation requirements to learn about the minimum hardware requirements.

Linux packages are available in our packages repository for:

• GitLab Enterprise Edition.
• GitLab Community Edition.

Check that the required GitLab version is available for your host operating system.

Supported platforms

GitLab provides Linux packages for the operating systems listed below. We build and distribute packages for these platforms. The table shows which GitLab versions are available for each operating system.

We provide Linux packages for operating systems based on vendor support lifecycles. Where long term support (LTS) versions exist, we target those, though not all operating systems follow an LTS model.

Package builds typically continue until an operating system reaches vendor end-of-life (EOL). We follow standard or maintenance support timelines, not extended or premium support periods.

We may discontinue package builds before vendor EOL due to:

• Business considerations: Including but not limited to low customer adoption, disproportionate maintenance costs, or strategic product direction changes.
• Technical constraints: When third-party dependencies, security requirements, or underlying technology changes make continued package builds impractical or impossible.
• Vendor actions: When operating system vendors make changes that fundamentally impact our software’s functionality or when required components become unavailable.

We aim to provide at least 6 months’ notice before discontinuing support for any operating system version. When technical limitations or vendor constraints require shorter notice, we will communicate changes as soon as possible.

Footnotes:

1. Known issues exist for running GitLab on ARM.

Unofficial, unsupported installation methods

The following installation methods are provided as-is by the wider GitLab community and are not supported by GitLab:

• Debian native package (by Pirate Praveen)
• FreeBSD package (by Torsten Zühlsdorff)
• Arch Linux package (by the Arch Linux community)
• Puppet module (by Vox Pupuli)
• Ansible playbook (by Jeff Geerling)
• GitLab virtual appliance (KVM) (by OpenNebula)
• GitLab on Cloudron (via Cloudron App Library)

End-of-life versions

You can find the list of deprecated operating systems and the final GitLab release for them in the table below:

Raspberry Pi OS (32-bit - Raspbian)

GitLab dropped support for Raspberry Pi OS (32 bit - Raspbian) with GitLab 17.11 being the last version available for the 32-bit platform. Starting with GitLab 18.0, you should move to Raspberry Pi OS (64 bit) and use the Debian arm64 package.

For information on backing up data on a 32-bit OS and restoring it to a 64-bit OS, see Upgrading operating systems for PostgreSQL.

Uninstall the Linux package

To uninstall the Linux package, you can opt to either keep your data (repositories, database, configuration) or remove all of them:

1. Optional. To remove all users and groups created by the Linux package before removing the package:

   sudo gitlab-ctl stop && sudo gitlab-ctl remove-accounts

   If you have a problem removing accounts or groups, run userdel or groupdel manually to delete them. You might also want to manually remove the leftover user home directories from /home/.

2. Choose whether to keep your data or remove all of them:

   • To preserve your data (repositories, database, configuration), stop GitLab and remove its supervision process:

     sudo systemctl stop gitlab-runsvdir sudo systemctl disable gitlab-runsvdir sudo rm /usr/lib/systemd/system/gitlab-runsvdir.service sudo systemctl daemon-reload sudo systemctl reset-failed sudo gitlab-ctl uninstall

   • To remove all data:

     sudo gitlab-ctl cleanse && sudo rm -r /opt/gitlab

3. Uninstall the package (replace with gitlab-ce if you have GitLab FOSS installed):

   apt

   # Debian/Ubuntu sudo apt remove gitlab-ee

   dnf

   # AlmaLinux/RHEL/Oracle Linux/Amazon Linux 2023 sudo dnf remove gitlab-ee

   zypper

   # OpenSUSE Leap/SLES sudo zypper remove gitlab-ee

   yum

   # Amazon Linux 2 sudo yum remove gitlab-ee

Ubuntu 22.04 FIPS

In GitLab 18.4 and later, FIPS builds are available for Ubuntu 22.04.

Before you upgrade:

1. Verify password hash migration for all active users: In GitLab 17.11 and later, user passwords are automatically rehashed with enhanced salt when users sign in.

   Any users who haven’t completed this hash migration will be unable to sign in to Ubuntu 22 FIPS installations and will need to perform a password reset.

   To find for users who have not migrated, use this Rake task before upgrading to Ubuntu 22.04.

2. Check the GitLab secrets JSON: Rails now requires stronger active dispatch salts to issue cookies. The Linux package uses static values with sufficient length by default on Ubuntu 22.04. However, you can customize these salts by setting the following keys in your Linux package configuration:

   gitlab_rails['signed_cookie_salt'] = 'custom value' gitlab_rails['authenticated_encrypted_cookie_salt'] = 'another custom value'

   The values are written to the gitlab-secrets.json and must be synchronized across all Rails nodes.

3. Prepare for OAuth token migration when upgrading to FIPS 140-3: GitLab 18.6.0, 18.5.2, and 18.4.4 introduced SHA512 hashing for OAuth tokens to comply with FIPS 140-3 requirements. Previously, GitLab used PBKDF2 without salt, which is incompatible with FIPS 140-3 compliant systems like Ubuntu 22.04.

   Note: This migration is only required when moving to FIPS 140-3 compliant operating systems (such as Ubuntu 22.04). No changes are needed if you are already running on older FIPS versions (such as Ubuntu 20.04) or staying on non-FIPS systems.

   When migrating from a non-FIPS instance or older FIPS version to a FIPS 140-3 instance:

   1. Upgrade to GitLab 18.4 or later.
   2. Allow sufficient time for active OAuth access tokens to be automatically rehashed during normal usage.
   3. Rotate OAuth application secrets to ensure all newly issued tokens use the FIPS-compliant hashing algorithm.
   4. Notify users that they may need to re-authenticate with OAuth-integrated applications if their tokens have not been used recently.