概要
GitLabのSelf-managed（自前で構築しているパターン）でかつ、Dockerを使用している場合のバージョンアップ方法について、まとまった記事が見つからなかったので記事を書くことにしました。
以前「バージョン上げるだけだろ～」と何も考えずにアップグレードして、GitLabの挙動がおかしくなった（リポジトリへのアクセスができなくなった）過去があるので、同じ過ちをしないためにも、この記事が活用されることを期待しております。
前提
この記事では以下の環境を前提とします。
- LinuxサーバにDocker image版GitLabを立てている
- Linuxの基本的なコマンドは打てる
- docker composeでGitLabコンテナを立てている
また環境は実際に構築した環境によって変わるため、この記事は万能薬というより、参考記事として活用してください。
アップデートの失敗に関する、いかなる責任も負いませんので、アップデートを実施する際には公式ドキュメントを参照の上、システムバックアップの取得など、注意して対応を行うようにしてください。
ここでの情報は、2026年2月現在の情報になります。
アップデート方法
まずGitLabコンテナにdocker compose exec gitlab bashなどで入ります。gitlabの部分はコンテナイメージの名前を設定してあげてください。
コンテナに無事入ることができたら、リポジトリなどのバックアップを実施します。
gitlab-backup create
を実行してください。
バックアップが作成できましたら、コンテナからexitし、docker compose downなどでコンテナを閉じてください。
次にGitLabの提供するUpgrade pathというサイトから、現在のGitLabバージョンから、引き上げたいバージョンを選択してください。
Distroはdocker、Editionは実際に構築しているGitLabで設定してください。
分からなければdocker-compose.ymlを見れば分かるかと思います。
GitLabのバージョンアップは、一気にバージョンを引き上げるのではなく、互換性のあるバージョンで少しずつ上げていきます。
例えば、Upgrade pathが以下のようなケースの場合、
17.8.7 -> 17.11.7 -> 18.2.8 -> 18.5.5 -> 18.8.2
とバージョンを上げていきます。
私の場合、docker composeでイメージ名を記載していたので、各バージョンのコンテナをdocker pullで取得し、一番小さなバージョンから順にdocker-compose.ymlを修正、docker compose up -dで起動していました。
起動自体は5分から10分程度かかります。
ここでかなり時間がたってもGitLabが起動しない場合は、docker compose psで起動時間を確認、再起動が繰り返していないかを確認してください。
再起動しているかどうかについては、上記コマンドで立ち上がり時間が確認できるので、かかった時間に対してあまりにも短い場合は再起動が繰り返されている可能性があると見ていいと思います。
この時は素直にdocker compose downでコンテナを閉じて、再度上げなおしてみてください。
これを繰り返し、最新バージョンまでバージョンを上げることができたら成功です。
参考
冒頭で取得したリポジトリのバックアップは/var/opt/gitlab/backups/にtar形式で保管されています。