<commit_before>---
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---

# Update GitLab installed with the Omnibus GitLab package **(FREE SELF)**

Before following these instructions, note the following:

- [Supported upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
  has suggestions on when to upgrade.
- If you are upgrading from a non-Omnibus installation to an Omnibus installation, see
  [Upgrading from a non-Omnibus installation to an Omnibus installation](convert_to_omnibus.md).

WARNING:
If you aren't [using the current major version](#mandatory-upgrade-paths-for-version-upgrades),
you **must** follow the
[supported upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
when updating to the current version.

## Background migrations

WARNING:
It's important to ensure that any background migrations have been fully completed
before upgrading to a new major version. Upgrading before background migrations have
finished may lead to data corruption.

To see the current size of the `background_migration` queue,
[check for background migrations before upgrading](https://docs.gitlab.com/ee/update/index.html#checking-for-background-migrations-before-upgrading).

## Version-specific changes

We recommend performing upgrades between major and minor releases no more than once per
week, to allow time for background migrations to finish. Decrease the time required to
complete these migrations by increasing the number of
[Sidekiq workers](https://docs.gitlab.com/ee/administration/operations/extra_sidekiq_processes.html)
that can process jobs in the `background_migration` queue.

Updating to major versions might need some manual intervention. For more information,
check the version your are updating to:

- [GitLab 13](gitlab_13_changes.md)
- [GitLab 12](gitlab_12_changes.md)
- [GitLab 11](gitlab_11_changes.md)

## Mandatory upgrade paths for version upgrades

From GitLab 10.8, upgrade paths are enforced for version upgrades by
default. This restricts performing direct upgrades that skip major versions (for
example 10.3 to 12.7 in one jump) that **can break GitLab
installations** due to multiple reasons like deprecated or removed configuration
settings, upgrade of internal tools and libraries, and so on. Users must follow
the [official upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
while upgrading their GitLab instances.

## Updating methods

There are two ways to update Omnibus GitLab:

- [Using the official repositories](#update-using-the-official-repositories).
- [Using a manually-downloaded package](#update-using-a-manually-downloaded-package).

Both will automatically back up the GitLab database before installing a newer
GitLab version. You may skip this automatic backup by creating an empty file
at `/etc/gitlab/skip-auto-backup`:

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

For safety reasons, you should maintain an up-to-date backup on your own if you plan to use this flag.

When upgrading to a new major version, remember to first [check for background migrations](https://docs.gitlab.com/ee/update/index.html#checking-for-background-migrations-before-upgrading).

Unless you are following the steps in [Zero downtime updates](#zero-downtime-updates), your GitLab application will not be available to users while an update is in progress. They will either see a "Deploy in progress" message or a "502" error in their web browser.

### Update using the official repositories

If you have installed Omnibus GitLab [Community Edition](https://about.gitlab.com/install/?version=ce)
or [Enterprise Edition](https://about.gitlab.com/install/), then the
official GitLab repository should have already been set up for you.

To update to the newest GitLab version, run:

- For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/):

  ```shell
  # Debian/Ubuntu
  sudo apt-get update
  sudo apt-get install gitlab-ee

  # Centos/RHEL
  sudo yum install gitlab-ee
  ```

- For GitLab Community Edition:

  ```shell
  # Debian/Ubuntu
  sudo apt-get update
  sudo apt-get install gitlab-ce

  # Centos/RHEL
  sudo yum install gitlab-ce
  ```

#### Multi-step upgrade using the official repositories

Linux package managers default to installing the latest available version of a
package for installation and upgrades. Upgrading directly to the latest major
version can be problematic for older GitLab versions that require a multi-stage
upgrade path.

When following an [upgrade path](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
spanning multiple versions, for each upgrade, specify the intended GitLab version
number in your package manager's install or upgrade command:

1. First, identify the GitLab version number in your package manager:

   ```shell
   # Ubuntu/Debian
   sudo apt-cache madison gitlab-ee
   # RHEL/CentOS 6 and 7
   yum --showduplicates list gitlab-ee
   # RHEL/CentOS 8
   dnf search gitlab-ee*
   ```

1. Then install the specific GitLab package:

   ```shell
   # Ubuntu/Debian
   sudo apt upgrade gitlab-ee=12.0.12-ee.0
   # RHEL/CentOS 6 and 7
   yum install gitlab-ee-12.0.12-ee.0.el7
   # RHEL/CentOS 8
   dnf install gitlab-ee-12.0.12-ee.0.el8
   # SUSE
   zypper install gitlab-ee=12.0.12-ee.0
   ```

### Update using a manually-downloaded package

If for some reason you don't use the official repositories, you can
[download the package and install it manually](../manual_install.md).

## Update Community Edition to Enterprise Edition

To upgrade an existing GitLab Community Edition (CE) server installed using the Omnibus GitLab
packages to GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) (EE), you install the EE
package on top of CE.

Upgrading from the same version of CE to EE is not explicitly necessary, and any standard upgrade<commit_msg>Switch from upgrade to install command<commit_after>---
stage: Enablement
group: Distribution
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---

# Update GitLab installed with the Omnibus GitLab package **(FREE SELF)**

Before following these instructions, note the following:

- [Supported upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
  has suggestions on when to upgrade.
- If you are upgrading from a non-Omnibus installation to an Omnibus installation, see
  [Upgrading from a non-Omnibus installation to an Omnibus installation](convert_to_omnibus.md).

WARNING:
If you aren't [using the current major version](#mandatory-upgrade-paths-for-version-upgrades),
you **must** follow the
[supported upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
when updating to the current version.

## Background migrations

WARNING:
It's important to ensure that any background migrations have been fully completed
before upgrading to a new major version. Upgrading before background migrations have
finished may lead to data corruption.

To see the current size of the `background_migration` queue,
[check for background migrations before upgrading](https://docs.gitlab.com/ee/update/index.html#checking-for-background-migrations-before-upgrading).

## Version-specific changes

We recommend performing upgrades between major and minor releases no more than once per
week, to allow time for background migrations to finish. Decrease the time required to
complete these migrations by increasing the number of
[Sidekiq workers](https://docs.gitlab.com/ee/administration/operations/extra_sidekiq_processes.html)
that can process jobs in the `background_migration` queue.

Updating to major versions might need some manual intervention. For more information,
check the version your are updating to:

- [GitLab 13](gitlab_13_changes.md)
- [GitLab 12](gitlab_12_changes.md)
- [GitLab 11](gitlab_11_changes.md)

## Mandatory upgrade paths for version upgrades

From GitLab 10.8, upgrade paths are enforced for version upgrades by
default. This restricts performing direct upgrades that skip major versions (for
example 10.3 to 12.7 in one jump) that **can break GitLab
installations** due to multiple reasons like deprecated or removed configuration
settings, upgrade of internal tools and libraries, and so on. Users must follow
the [official upgrade paths](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
while upgrading their GitLab instances.

## Updating methods

There are two ways to update Omnibus GitLab:

- [Using the official repositories](#update-using-the-official-repositories).
- [Using a manually-downloaded package](#update-using-a-manually-downloaded-package).

Both will automatically back up the GitLab database before installing a newer
GitLab version. You may skip this automatic backup by creating an empty file
at `/etc/gitlab/skip-auto-backup`:

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

For safety reasons, you should maintain an up-to-date backup on your own if you plan to use this flag.

When upgrading to a new major version, remember to first [check for background migrations](https://docs.gitlab.com/ee/update/index.html#checking-for-background-migrations-before-upgrading).

Unless you are following the steps in [Zero downtime updates](#zero-downtime-updates), your GitLab application will not be available to users while an update is in progress. They will either see a "Deploy in progress" message or a "502" error in their web browser.

### Update using the official repositories

If you have installed Omnibus GitLab [Community Edition](https://about.gitlab.com/install/?version=ce)
or [Enterprise Edition](https://about.gitlab.com/install/), then the
official GitLab repository should have already been set up for you.

To update to the newest GitLab version, run:

- For GitLab [Enterprise Edition](https://about.gitlab.com/pricing/):

  ```shell
  # Debian/Ubuntu
  sudo apt-get update
  sudo apt-get install gitlab-ee

  # Centos/RHEL
  sudo yum install gitlab-ee
  ```

- For GitLab Community Edition:

  ```shell
  # Debian/Ubuntu
  sudo apt-get update
  sudo apt-get install gitlab-ce

  # Centos/RHEL
  sudo yum install gitlab-ce
  ```

#### Multi-step upgrade using the official repositories

Linux package managers default to installing the latest available version of a
package for installation and upgrades. Upgrading directly to the latest major
version can be problematic for older GitLab versions that require a multi-stage
upgrade path.

When following an [upgrade path](https://docs.gitlab.com/ee/update/index.html#upgrade-paths)
spanning multiple versions, for each upgrade, specify the intended GitLab version
number in your package manager's install or upgrade command:

1. First, identify the GitLab version number in your package manager:

   ```shell
   # Ubuntu/Debian
   sudo apt-cache madison gitlab-ee
   # RHEL/CentOS 6 and 7
   yum --showduplicates list gitlab-ee
   # RHEL/CentOS 8
   dnf search gitlab-ee*
   ```

1. Then install the specific GitLab package:

   ```shell
   # Ubuntu/Debian
   sudo apt install gitlab-ee=12.0.12-ee.0
   # RHEL/CentOS 6 and 7
   yum install gitlab-ee-12.0.12-ee.0.el7
   # RHEL/CentOS 8
   dnf install gitlab-ee-12.0.12-ee.0.el8
   # SUSE
   zypper install gitlab-ee=12.0.12-ee.0
   ```

### Update using a manually-downloaded package

If for some reason you don't use the official repositories, you can
[download the package and install it manually](../manual_install.md).

## Update Community Edition to Enterprise Edition

To upgrade an existing GitLab Community Edition (CE) server installed using the Omnibus GitLab
packages to GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) (EE), you install the EE
package on top of CE.

Upgrading from the same version of CE to EE is not explicitly necessary, and any standard upgrade
{'fraction_non_alphanumeric': 0.08041697691734921, 'fraction_numerical': 0.009597087780259783, 'mean_word_length': 4.53987167736022, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 24, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '724219', 'n_tokens_mistral': 3606, 'n_tokens_neox': 3273, 'n_words': 1370}