Ubuntu24.04上に構築しているGitLabサーバーで、パッケージ更新のためにapt updateを実行したところ、最新バージョンに一気にアップデートできずエラーが発生しました。
今回は、17.9.1から18.11.3まで上げたときに、実際に発生したエラー内容、原因、対応方法を整理します。
はじめに
Ubuntu 24.04上に構築しているGitLabをしばらく放置していたため、最新バージョンにアップデートしようとしておりました。
最初は、通常のUbuntuパッケージと同じように、
sudo apt update
sudo apt upgrade -y
、でまとめて更新できると考えていました。
しかし、GitLabは通常のパッケージとは異なり、一気に最新バージョンへアップデートできない場合があるみたいです。
公式ドキュメントより
今回の環境では、最初のバージョンは以下でした。
GitLab Version: 17.9.1-ee
OS: Ubuntu 24.04
最終的には、以下のバージョンまでアップデートできました。
GitLab Version: 18.11.3-ee
この記事では、GitLab17.9.1から18.11.3へアップデートする中で発生したエラーと、対応内容を整理します。
■結論
GitLabをアップデートするときは、以下の点に注意が必要です。
apt upgrade -yで一気に上げようとしない- GitLabの"required upgrade stops"を確認する
- 各中継バージョンで"background migration"の完了を確認する
GitLab公式ドキュメントでも、GitLab18系では18.2、18.5、18.8、18.11が"required upgrade stops"として案内されています。また、GitLab17系では17.11.7などの停止バージョンが定義されています。
公式ドキュメントより
今回の実際のアップグレード経路は、概ね以下のようになりました。
17.9.1
→ 17.9.7
→ 17.11.7
→ 18.2.8
→ 18.5.5
→ 18.8.4
→ 18.11.3
■事前確認
まず、現在のGitLabバージョンを確認しました。
sudo gitlab-rake gitlab:env:info
出力結果は以下です。
GitLab information
Version: 17.9.1-ee
System: Ubuntu 24.04
この時点では、GitLab 17.9.1-eeが稼働していました。
次に、バックアップを取得しました。
sudo gitlab-backup create
バックアップは正常終了し、以下のようなファイルが作成されました。
1778565594_2026_05_12_17.9.1-ee_gitlab_backup.tar
ただし、GitLabのバックアップにはgitlab.rbやgitlab-secrets.jsonが含まれません。GitLab 公式ドキュメントでも、これらの設定ファイルは別途バックアップが必要と案内されています。
公式ドキュメントより
そのため、設定ファイルも別途バックアップしておく必要があります。
sudo tar czf /var/opt/gitlab/gitlab-config-backup-$(date +%Y%m%d%H%M%S).tar.gz /etc/gitlab
■エラー1：17.9から18.11へ一気に上げようとして失敗
次に、OS パッケージも含めて更新するために以下を実行しました。
sudo apt upgrade -y
すると、GitLabも更新対象に含まれてしまい、17.9から18.11へ一気に上がろうとしました。
その結果、以下のエラーで停止しました。
gitlab preinstall: It seems you are upgrading from 17.9 to 18.11.
gitlab preinstall: It is required to upgrade to the latest 18.8.x version first before proceeding.
GitLabは、バージョンによって必要な中継バージョンを踏む必要があります。GitLab公式でも、GitLab 18系の"required upgrade stops"は 18.2、18.5、18.8、18.11とされています。
公式ドキュメントより
この時点で、apt upgrade -yで一気に上げるのは危険だと分かりました。
■エラー2：17.9から18.8へ上げようとして失敗
"18.11"に直接上げられないなら、"18.8"を先に入れればよいと考え、次のように実行しました。
sudo apt install gitlab-ee=18.8.4-ee.0
しかし、これも失敗しました。
gitlab preinstall: It seems you are upgrading from 17.9 to 18.8.
gitlab preinstall: It is required to upgrade to the latest 18.5.x version first before proceeding.
つまり、17.9 から 18.8 へも直接は上げられません。
■エラー3：17.9から18.2へ上げようとして失敗
次に、18系の最初の"required upgrade stop"である"18.2"へ上げようとしました。
sudo apt install gitlab-ee=18.2.8-ee.0
しかし、これも失敗しました。
gitlab preinstall: It seems you are upgrading from 17.9 to 18.2.
gitlab preinstall: It is required to upgrade to the latest 17.11.x version first before proceeding.
ここでようやく、17系の最後の中継点として17.11.xが必要であることが分かりました。
GitLab公式のアップグレードパスでも、GitLab 17系の"required upgrade stop"として17.11.7が示されています。
公式ドキュメントより
■17.11.7へのアップグレード
次に、17.11.7を指定してアップグレードしました。
sudo apt install gitlab-ee=17.11.7-ee.0
アップグレード後、以下を確認しました。
gitlab-ctl status
gitlab-rake gitlab:check
gitlab-rake gitlab:env:info
確認結果では、主要サービスはすべて起動していました。
run: gitaly
run: gitlab-workhorse
run: nginx
run: postgresql
run: puma
run: redis
run: sidekiq
また、GitLabのバージョンも17.11.7-eeになっていました。
GitLab information
Version: 17.11.7-ee
"17.11.7"へ上げたあと、次に進む前に"background migration"を確認しました。
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
最初は複数件残っていましたが、しばらく待つことで減っていきました。
最後は0件になりました。
(0 rows)
GitLab公式では、アップグレード経路上では、次の"required upgrade stop"へ進む前に"background migration" の完了を待つことが案内されています。
公式ドキュメントより
■18.2.8へのアップグレード
"background migration"が0件になったため、次に"18.2.8"へ進みました。
sudo apt install gitlab-ee=18.2.8-ee.0
アップグレード後は、毎回以下を確認しました。
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check
sudo gitlab-rake gitlab:env:info
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
■18.5.5、18.8.4、18.11.3へ順番にアップデート
その後は、"required upgrade stops"に従って順番に進めました。
sudo apt install gitlab-ee=18.5.5-ee.0
sudo apt install gitlab-ee=18.8.4-ee.0
sudo apt install gitlab-ee=18.11.3-ee.0
最終的に、GitLabは以下の状態になりました。
GitLab information
Version: 18.11.3-ee
gitlab:env:infoでは、Ruby、Redis、PostgreSQL、Gitalyなども更新されていることが確認できました。
Ruby Version: 3.3.10
Redis Version: 7.2.11
DB Version: 17.8
Gitaly Version: 18.11.3
■今回の失敗から学んだこと
今回の一番大きな学びは、GitLabはapt upgradeで一気に最新化してはいけないということです。
Ubuntuの通常パッケージであれば、apt upgrade -yでまとめて更新することが多いです。
しかし、GitLabは内部で"PostgreSQL、Redis、Gitaly、Sidekiq"など複数のコンポーネントを含んでいます。また、"DB migration"や"background migration"もあります。
そのため、バージョンを飛ばすと、preinstallの段階で止められたり、"background migration"が残った状態で次に進めなくなったりします。
GitLab公式ドキュメントでも、"required upgrade stop"を経由し、各バージョンで"background migration"の完了を待つことが案内されています。
公式ドキュメントより
■今回使った確認コマンド
●現在バージョン確認
sudo gitlab-rake gitlab:env:info
●GitLab状態確認
sudo gitlab-ctl status
●GitLab整合性確認
sudo gitlab-rake gitlab:check
●secrets確認
sudo gitlab-rake gitlab:doctor:secrets
●background migration確認
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
●利用可能なGitLabバージョン確認
apt-cache madison gitlab-ee
特定バージョンだけ確認する場合です。
apt-cache madison gitlab-ee | grep "18.5"
●GitLabを勝手にアップデートさせない
sudo apt-mark hold gitlab-ee
解除する場合です。
sudo apt-mark unhold gitlab-ee
■安全なアップグレード手順の例
今回の経験を踏まえると、GitLabのアップグレードは次のように進めるのが安全です。
# 1. 現在バージョン確認
sudo gitlab-rake gitlab:env:info
# 2. バックアップ取得
sudo gitlab-backup create
sudo tar czf /var/opt/gitlab/gitlab-config-backup-$(date +%Y%m%d%H%M%S).tar.gz /etc/gitlab
# 3. 事前チェック
sudo gitlab-rake gitlab:check
sudo gitlab-rake gitlab:doctor:secrets
# 4. background migration確認
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
# 5. 必要な中継バージョンを確認
apt-cache madison gitlab-ee
# 6. バージョン指定でアップグレード
sudo apt install gitlab-ee=<指定バージョン>
# 7. アップグレード後確認
sudo gitlab-ctl status
sudo gitlab-rake gitlab:check
sudo gitlab-rake gitlab:env:info
# 8. background migrationが0rowsになるまで待つ
sudo gitlab-psql -c "SELECT job_class_name, table_name, column_name, job_arguments FROM batched_background_migrations WHERE status NOT IN(3, 6);"
まとめ
GitLabのアップデートは、単純にapt upgrade -yを実行すればよいものではありませんでした。
今回、17.9.1から18.11.3へ上げるまでに、以下の問題に遭遇しました。以下の一部エラーについては、本記事では取り上げていません。
- GitLab APTリポジトリのGPGキー期限切れ
17.9 → 18.11の直接アップグレード失敗17.9 → 18.8の直接アップグレード失敗17.9 → 18.2の直接アップグレード失敗17.11.7への中継が必要- background migrationの残存
- background migration finalize時のJSON引数ミス
sent_notificationsのパーティション不足18.5.5アップグレード前のDBバックアップ失敗
最終的には、GitLabの"required upgrade stops"に従い、以下の順番で進めることで最新化できました。
17.9.1
→ 17.9.7
→ 17.11.7
→ 18.2.8
→ 18.5.5
→ 18.8.4
→ 18.11.3
GitLabを運用している場合は、OS パッケージと同じ感覚で一括更新するのではなく、公式のアップグレードパスを確認し、バージョン指定で段階的にアップデートすることが重要です。
参考リンク:GitLab公式ドキュメント
↓ほかの協栄情報メンバーのGitLabについての記事を公開しています。ぜひ参考にしてみてください。
■Ubuntu24.04でGitLabのapt updateがEXPKEYSIGエラーになったときの対応(齊藤弘樹)
■Amazon EC2を利用して、GitLabサーバを構築してみた【AWS】(齊藤弘樹)
■GitLabサーバにRunnerをインストールしてみた(齊藤弘樹)