Upgrade GitLab Helm chart instances

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

Upgrade a GitLab Helm chart instance to a later version of GitLab.

Zero-downtime upgrades are only available for cloud-native GitLab instances by using GitLab Operator.

Prerequisites

Before upgrading a GitLab Helm chart instance:

  1. Consult information you need before you upgrade.
  2. Because GitLab Helm chart versions don’t follow the same numbering as GitLab versions, see version mappings to find the GitLab Helm chart version you need.
  3. See the CHANGELOG corresponding to the specific release you want to upgrade to.
  4. If you’re upgrading from versions of the GitLab Helm chart version earlier than 8.x, see the GitLab documentation archives to access older versions of the documentation.
  5. Perform a backup.

Upgrade a GitLab Helm chart instance

To upgrade a GitLab Helm chart instance:

  1. Consider turning on maintenance mode during the upgrade to restrict users from write operations to help not disturb any workflows.

  2. Upgrade GitLab Runner to the same version as your target GitLab version.

  3. Follow the deployment documentation step by step.

  4. Extract your previously provided values:

    helm get values gitlab > gitlab.yaml

  5. Decide on all the values you need to carry through as you upgrade. You should only keep a minimal set of values that you want to explicitly set and pass those during the upgrade process. You should otherwise rely on GitLab default values.

  6. Perform the upgrade, with values extracted and reviewed in previous steps:

    helm upgrade gitlab gitlab/gitlab \
  --version <new version> \
  -f gitlab.yaml \
  --set gitlab.migrations.enabled=true \
  --set ...

    During a major database upgrade, you should set gitlab.migrations.enabled to false. Ensure that you explicitly set it back to true for future updates.

After you upgrade:

  1. If enabled, turn off maintenance mode.
  2. Run upgrade health checks.

Upgrade the bundled PostgreSQL

Only perform these steps if you are using the bundled PostgreSQL chart (postgresql.install is true).

To upgrade the bundled PostgreSQL:

  1. Decide which version of PostgreSQL to upgrade to.
  2. Prepare the existing database.
  3. Delete existing PostgreSQL data.
  4. Update the postgresql.image.tag value to the required version of PostgreSQL and reinstall the chart to create a new PostgreSQL database.
  5. Restore the database.