Upgrade GitLab Helm chart instances

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

Upgrades must follow a supported upgrade path. Because GitLab Helm chart versions don’t follow the same numbering as GitLab versions, see the version mappings between them.

Prerequisites

Before upgrading a GitLab Helm chart instance:

• Check the CHANGELOG corresponding to the specific release you want to upgrade to.
• Look for any upgrade notes for the GitLab Helm chart version you’re upgrading to.
• 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.
• Take a backup.

Upgrade a GitLab Helm chart instance

To upgrade a GitLab Helm chart instance:

1. Follow the deployment documentation step by step.

2. Extract your previously provided values:

   helm get values gitlab > gitlab.yaml

3. 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.

4. 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.

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.