How to do a Gitlab Major version upgrade
========================================

Published  : 1 January 2025
Reading    : 2 min
Tags       : gitlab
URL        : https://ctrl-find.nl/posts/gitlab_upgrade/
Plain text : https://ctrl-find.nl/posts/gitlab_upgrade/index.txt

------------------------------------------------------------

## Upgrade Path

You can check the upgrade path on the following site: <https://gitlab-com.gitlab.io/support/toolbox/upgrade-path/>.
This website is made by Gitlab, and will give a good overview about changes and new features for the upgrades you selected.

## Checks

<https://docs.gitlab.com/ee/update/index.html#checking-for-background-migrations-before-upgrading>
Check pending and failed DB migrations.

```bash
gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.queued.count'
gitlab-rails runner -e production 'puts Gitlab::Database::BackgroundMigration::BatchedMigration.with_status(:failed).count'
```

OPTIONAL: Check pending elasticsearch migrations

```bash
gitlab-rake gitlab:elastic:list_pending_migrations
```

Update check

```bash
gitlab-rake gitlab:check SANITIZE=true
```

## Pre-upgrade

Create a snapshot on the environment you are hosting your gitlab environment.\
Set instance in maintenance mode:

```bash
gitlab-rails runner '::Gitlab::CurrentSettings.update!(maintenance_mode: true)'
```

Create a gitlab backup of latest version!
<https://docs.gitlab.com/ee/administration/backup_restore/>
Make sure gitlab has the rights to read and write with the backup.

Disable advanced search before upgrading to a new major version.
This is because of the index changes that are possible coming with new version.
Checkout my reindex guide on gitlab advanced search to re-enable it.

Before the upgrade is started we need to stop subprocess puma and sidekiq on the gitlab server

```bash
gitlab-ctl stop sidekiq && gitlab-ctl stop puma
```

We can check with following command if the services are really stopped.

```bash
gitlab-ctl status
```

## The Upgrade

<https://docs.gitlab.com/ee/update/package/index.html>
Upgrading to a specific version:

```bash
gitlab-ee-<gitlab_version>-ee.0.el<distribution_version>
```

Upgrade to latest version:

```bash
yum install gitlab-ee
```

Reconfigure and restart gitlab instance:

```bash
gitlab-ctl reconfigure
gitlab-ctl restart
```

Turn maintenance mode off:

```bash
gitlab-rails runner '::Gitlab::CurrentSettings.update!(maintenance_mode: false)'
```

## Enjoy newer version

Login on UI, to checkout the UI and the new features.


------------------------------------------------------------
NAVIGATION

  [index]  https://ctrl-find.nl/posts/index.txt

  [<< prev] How to reindex Gitlab Advanced_search
            https://ctrl-find.nl/posts/gitlab_reindex/index.txt


  [next >>] How to configure Gitlab Advanced Search
            https://ctrl-find.nl/posts/gitlab_advanced_search/index.txt

------------------------------------------------------------

CTRL-Find — Debugging all systems
https://ctrl-find.nl/