From ae9c5941b0481aff9f7f1aff058b71fa2078fde6 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 20 Oct 2025 15:48:04 +1000 Subject: [PATCH 1/2] Refine upgrade instructions documentation --- doc/installation/upgrade.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/installation/upgrade.md b/doc/installation/upgrade.md index d17bace8bf..dbfb24f016 100644 --- a/doc/installation/upgrade.md +++ b/doc/installation/upgrade.md @@ -14,10 +14,6 @@ title: Upgrade GitLab Helm chart instances Upgrade a GitLab Helm chart instance to a later version of GitLab. -Upgrades must follow a supported [upgrade path](https://docs.gitlab.com/update/upgrade_paths/). Because GitLab Helm -chart versions don't follow the same numbering as GitLab versions, see the [version mappings](version_mappings.md) -between them. - {{< alert type="note" >}} **Zero-downtime upgrades** are only available for cloud-native GitLab instances by using @@ -29,18 +25,21 @@ between them. Before upgrading a GitLab Helm chart instance: -- Check the [CHANGELOG](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) corresponding to the - specific release you want to upgrade to. -- Look for any [upgrade notes](https://docs.gitlab.com/update/versions/) 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](https://docs.gitlab.com/archives/) to access older versions of the documentation. -- Take a [backup](../backup-restore/_index.md). +1. Consult [information you need before you upgrade](https://docs.gitlab.com/update/plan_your_upgrade/). +1. Because GitLab Helm chart versions don't follow the same numbering as GitLab versions, see + [version mappings](version_mappings.md) to find the GitLab Helm chart version you need. +1. See the [CHANGELOG](https://gitlab.com/gitlab-org/charts/gitlab/blob/master/CHANGELOG.md) corresponding to the + specific release you want to upgrade to. +1. If you're upgrading from versions of the GitLab Helm chart version earlier than 8.x, see the + [GitLab documentation archives](https://docs.gitlab.com/archives/) to access older versions of the documentation. +1. Perform a [backup](../backup-restore/_index.md). -## Upgrade a GitLab Helm chart instance +## Upgrade GitLab -To upgrade a GitLab Helm chart instance: +To upgrade GitLab: +1. Consider [turning on maintenance mode](https://docs.gitlab.com/administration/maintenance_mode/) during the upgrade. +1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. 1. Follow the [deployment documentation](deployment.md) step by step. 1. Extract your previously provided values: @@ -64,6 +63,11 @@ To upgrade a GitLab Helm chart instance: 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](https://docs.gitlab.com/administration/maintenance_mode/#disable-maintenance-mode). +1. Run [upgrade health checks](https://docs.gitlab.com/update/plan_your_upgrade/#run-upgrade-health-checks). + ## Upgrade the bundled PostgreSQL Only perform these steps if you are using the bundled PostgreSQL chart (`postgresql.install` is `true`). -- GitLab From 4177374f711ccf5732e63969d99c8fe4f0733a29 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Tue, 21 Oct 2025 08:44:45 +1000 Subject: [PATCH 2/2] Explain why someone might turn on maintenance mode --- doc/installation/upgrade.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/installation/upgrade.md b/doc/installation/upgrade.md index dbfb24f016..5bbce2b61e 100644 --- a/doc/installation/upgrade.md +++ b/doc/installation/upgrade.md @@ -38,7 +38,8 @@ Before upgrading a GitLab Helm chart instance: To upgrade GitLab: -1. Consider [turning on maintenance mode](https://docs.gitlab.com/administration/maintenance_mode/) during the upgrade. +1. Consider [turning on maintenance mode](https://docs.gitlab.com/administration/maintenance_mode/) during the upgrade + to restrict users from write operations to help not disturb any workflows. 1. [Upgrade GitLab Runner](https://docs.gitlab.com/runner/install/) to the same version as your target GitLab version. 1. Follow the [deployment documentation](deployment.md) step by step. 1. Extract your previously provided values: -- GitLab