GitLab 18.4から19.5へ上げるには、18.5・18.8・18.11・19.2の4つの版を順に経由する必要があります。GitLabのアップグレードパスは、途中で必ず止まらなければならない「必須アップグレードストップ（必須停止点）」と、各停止点で待つバックグラウンドマイグレーションで決まる仕組みです。この記事では、停止点が置かれる仕組みと一覧、稼働中の版から経由する版を割り出す手順、Linuxパッケージで停止点を1段ずつ上げるコマンド、そして四半期ごとに上げる運用の判断基準を、2026年11月13日時点の公式ドキュメントをもとに整理します。
まとめ：GitLabのアップグレードパスは停止点の経由と移行完了の確認で決まる
GitLab 17.5以降、必須停止点はマイナー版の2・5・8・11に固定されました。18系なら18.2・18.5・18.8・18.11、19系なら19.2・19.5・19.8・19.11です。現在の版と目標の版のあいだにある停止点は、ひとつも飛ばせません。
手順は単純です。稼働中の版をAPIで取り、GitLabサポートが公開しているUpgrade Path toolで経由する版を確定させます。各停止点にはそのマイナー版の最新パッチを入れ、バッチ型バックグラウンドマイグレーションの未完了が0行になってから次へ進みます。
運用面で先に示す結論は、停止点の周期に合わせた更新計画です。停止点は3か月に1回しか来ないので、四半期に1度、最新の停止点まで上げる運用にすれば毎回1〜2段で済みます。1年以上放置すると経由は4段以上になり、19.0のPostgreSQL 17要件のような前提条件の確認も積み上がります。
GitLabの更新経路の仕組み｜停止点がx.2・x.5・x.8・x.11になる理由
アップグレードパスは「現在の版から目標の版まで、どの版を順に入れるか」の経路です。GitLabは毎月リリースされますが、すべての版を順に入れる必要はありません。入れなければならないのは停止点だけです。
停止点を飛ばせない理由は前の版のバックグラウンドマイグレーション完了
GitLabのデータベース変更には、アップグレード中に終わる通常のマイグレーションと、アップグレード後にSidekiqが時間をかけて進めるバッチ型バックグラウンドマイグレーションがあります。後者が終わっていない状態で次の版へ進むと、新しい版が前提とするデータの形がそろっておらず、マイグレーションが失敗します。
停止点は「ここまでのバックグラウンドマイグレーションを必ず完了させる版」です。公式のアップグレードパスのページも、停止点へ上げたあと、次の停止点へ進む前にバックグラウンドマイグレーションの完了を待つよう求めています。停止点を飛ばすと、データ移行が欠けたまま新しい版のマイグレーションが走る状態を作ります。
18系・19系の必須停止点一覧と16系・17系に残る条件付き停止点
停止点の一覧は次のとおりです。16系・17系には、大規模環境や特定の機能を使う環境だけに必要な条件付きの停止点が混ざります。
| メジャー版 | 必須停止点 | 条件付きの停止点 |
|---|---|---|
| 16系 | 16.3.9、16.7.10、16.11.10 | 16.0.10、16.1.8、16.2.11 |
| 17系 | 17.3・17.5・17.8・17.11 | 17.1.8 |
| 18系 | 18.2、18.5、18.8、18.11 | なし |
| 19系 | 19.2、19.5、19.8、19.11 | なし（19.8・19.11は未リリース） |
表の16系の条件付き停止点である16.0.10、16.1.8、16.2.11には、利用者数・CI変数の履歴・NPMパッケージ利用などの条件があります。17系の17.1.8は、ci_pipeline_messagesテーブルが大きい環境に必要な条件付き停止点です。17系の必須停止点を版番号まで書くと、17.3.7・17.5.5・17.8.7・17.11.7です。
18系以降は条件付きの停止点がなくなり、どの環境でも同じ4つを通ります。16系・17系に残っている環境では、自社が条件に当たるかを判断する手間がかかるので、迷ったら条件付きの版も経由する前提で計画を組むほうが安全です。
2026年11月時点の保守対象19.5・19.4・19.3とリリースの周期
GitLabのリリース・保守ポリシーでは、2026年11月13日時点の保守対象は19.5（バグ修正とセキュリティ修正）、19.4と19.3（セキュリティ修正のみ）です。マイナー版は毎月第3木曜、パッチ版はその前週と翌週の水曜に出ます。次のメジャー版20.0は2027年5月20日の予定です。
停止点の周期と保守対象を重ねると、計画の立て方が見えます。19.2は停止点ですが、すでにセキュリティ修正の対象外です。19.2で止めたまま運用を続けると、脆弱性の修正版が届きません。停止点はあくまで通過点で、最終的には保守対象の版まで上げ切る計画にします。
稼働中の版からUpgrade Path toolで経由する版を割り出す手順
経路を決めるには、正確な現在の版と、目標の版の2つが要ります。管理画面のヘルプページでも版は見えますが、複数のインスタンスを管理するならAPIで取るほうが確実です。
Metadata APIのcurl例で稼働中の版とCE・EEの区別を取得する
Metadata APIの GET /version を呼ぶと、版とリビジョン、Enterprise Editionかどうかが返ります。パッケージ名（gitlab-ceかgitlab-eeか）を取り違えないために、EEかどうかも同時に控えます。
curl --request GET \
--header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
--url "https://gitlab.example.com/api/v4/version"
# 応答例（形式は公式ドキュメントの例と同じ）
# {"version":"18.4.6-ee","revision":"xxxxxxxxxxx","enterprise":true}サーバーに入れるなら sudo gitlab-rake gitlab:env:info でも版とエディションを確認できます。トークンの発行とスコープの選び方は、同じグループのGitLabとは：構成要素・CEとEEの違いでCEとEEの区別とあわせて押さえておくと迷いません。
Upgrade Path toolに現在の版と目標の版を入れて停止点を一覧にする
経由版の割り出しには、GitLabサポートチームが保守しているUpgrade Path toolを使います。現在の版、目標の版、エディション（CE／EE）、ディストリビューションを選ぶと、経由する版がパッチ番号つきで並びます。
ツールが示す版は、各マイナー版のその時点の最新パッチです。公式ドキュメントも「16.8.0ではなく16.8.7」のように、マイナー版の最初のパッチではなく最新パッチを選ぶよう勧めています。最初のパッチには、アップグレード処理そのものの不具合が残っていることがあるためです。
18.4から19.5へ上げる例で数える経由版4つと作業の回数
18.4系で止まっている環境を、保守対象の最新である19.5系へ上げる場合を数えます。18.4と19.5のあいだにある停止点は18.5・18.8・18.11・19.2の4つです。19.5も停止点なので、ここで移行の完了を待ってから運用に戻します。
- 18.4系 → 18.5系の最新パッチ（停止点）
- 18.5系 → 18.8系の最新パッチ（停止点）
- 18.8系 → 18.11系の最新パッチ（停止点・単一ノードのLinuxパッケージではPostgreSQL 17.7へ自動で上がる）
- 18.11系 → 19.2系の最新パッチ（停止点・19.0のPostgreSQL 17要件をここで満たしている必要がある）
- 19.2系 → 19.5系の最新パッチ（停止点・Duo Agent Platformの移行完了を待つ）
この経路で必要なパッケージの入れ替えは合計5回です。各段でバックグラウンドマイグレーションの完了を待つため、データ量の多いインスタンスでは1日で終わらないこともあります。18.10から上げる場合の経路はGitLab 18.10の保守終了と19.4・19.5への移行経路で、版ごとの修正内容とあわせて扱っています。
経由する版ごとに確認するアップグレードノートとPostgreSQL・OSの前提
経路が決まったら、経由する版それぞれのアップグレードノートを読みます。停止点を守っていても、OSやデータベースの前提を満たしていなければその版で止まります。
19.0のPostgreSQL 17要件とUbuntu 20.04・SUSE系の提供終了
GitLab 19のアップグレードノートによると、19.0からPostgreSQLの最低要件は17になりました。単一ノードのLinuxパッケージなら18.11で同梱のPostgreSQLが17.7へ自動で上がりますが、外部のPostgreSQL（Amazon RDSなど）やHA構成では、19系へ進む前に自分で17へ上げる必要があります。
OSの前提も変わっています。19.0でUbuntu 20.04向けとSUSE系向けのLinuxパッケージは提供が終わりました。Ubuntu 20.04で動かしている環境は、18.11まで上げた時点でOSの移行を先に済ませないと19系のパッケージが入りません。ほかに、外部Redis 6はRedis 7.0以上かValkey 7.2への移行が必要で、/etc/gitlab/gitlab.rb に mattermost[...] の設定が残っていると gitlab-ctl reconfigure が止まります。
避けるパッチ版18.11.0・18.11.1と19.3・19.4の監査イベント不具合
停止点のなかには、特定のパッチ版を避けるよう明記されたものもあるため、適用前の確認が必要です。GitLab 18のアップグレードノートは、CIジョブが CI_JOB_TOKEN でコンテナイメージを取得している環境に対して、18.11.0と18.11.1へ上げないよう求めています。18.11.7ではMattermostの設定を消していても19.0への更新が止まる事例があり、18.11.9以降を先に入れる回避策が案内されています。
19系にも同じ種類の注意があります。19.3.0〜19.3.7と19.4.0〜19.4.3は、監査イベントのストリーミングでRedisが埋まりGitLabが止まることがあり、19.3.8と19.4.5で直っています。どれも「各マイナー版の最新パッチを入れる」原則を守れば踏まずに済む不具合です。
19.5の停止点でDuo Agent Platformの移行を待つ理由とディスク容量
19.5でバックグラウンド実行される処理のひとつが、Duo Agent Platformのチェックポイントの移行です。アップグレードノートは、19.5より後へ進む前にこの移行を完了させること、移行中はPostgreSQLのディスク使用量が増えることを明記しています。19.5へ上げる前に、データベースのボリュームの空きを確認しておきます。
Agent for Kubernetesの接続先も、19.5から既定でネイティブgRPCになりました。途中のプロキシがHTTP/2を通さない構成では、WebSocketのアドレスを明示して設定しないとエージェントがつながらなくなります。
Linuxパッケージで停止点を1つずつ上げるコマンドと移行完了の確認
ここからはUbuntu／DebianのLinuxパッケージ版を例に、作業のコマンドを示します。Docker Composeで動かしている環境は、イメージタグを停止点の版に書き換えて docker compose pull する手順になり、GitLabオンプレ構築：Docker Composeで本番運用する手順のアップグレードの章で扱っています。
作業前に流す5つのヘルスチェックとバックアップ・設定ファイルの退避
Before you upgradeが挙げる事前チェックは次の5つです。最後のコマンドは結果をファイルに残し、問題が起きたときにサポートへ渡せるようにします。
sudo gitlab-rake gitlab:check
sudo gitlab-rake gitlab:doctor:secrets
sudo gitlab-rake gitlab:geo:check # Geoを使う場合のみ
sudo gitlab-rake gitlab:db:diagnostics:search_path
sudo gitlab-rake gitlab:db:diagnostics > db_diagnostics.txt
# バックアップと設定ファイルの退避（設定ファイルはバックアップに含まれない）
sudo gitlab-backup create
sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab.rb /secure/backup/管理エリアの「Monitoring」→「Database diagnostics」で、Anti-wraparoundのバッジが付いたvacuumが走っていないかも見ます。走っている場合は止めずに完了を待ってから始めるよう、公式は案内しています。
aptで停止点の最新パッチを順に入れ移行が0行になるまで待つスクリプト
Linuxパッケージのアップグレード手順は、経路に複数の版がある場合、各段でパッケージの版を明示して入れるよう求めています。次のスクリプトは、停止点のマイナー版ごとにリポジトリにある最新パッチを apt-cache madison で拾い、入れたあとバッチ型バックグラウンドマイグレーションの未完了が0行になるまで待ちます。
#!/usr/bin/env bash
# 18.4系から19.5系へ、必須停止点を1段ずつ上げる（EEの例。CEは gitlab-ce に置き換える）
set -euo pipefail
PKG_NAME=gitlab-ee
STOPS="18.5 18.8 18.11 19.2 19.5"
sudo apt update
for MINOR in $STOPS; do
# 停止点のマイナー版で、リポジトリにある最新パッチを選ぶ
VER=$(apt-cache madison "$PKG_NAME" | awk '{print $3}' | grep "^${MINOR}\." | sort -V | tail -1)
echo "==> ${PKG_NAME}=${VER} を入れます"
sudo apt install -y "${PKG_NAME}=${VER}"
# バッチ型バックグラウンドマイグレーションの未完了が0行になるまで待つ
until [ "$(sudo gitlab-psql -t -A -c "SELECT count(*) FROM batched_background_migrations WHERE status NOT IN(3, 6);")" = "0" ]; do
echo "移行の完了待ち（${VER}）"; sleep 300
done
sudo gitlab-rake gitlab:check
done待ち合わせのSQLは移行の確認手順に載っている条件をそのまま件数にしたものです。公式に示された全件完了の判定条件は、未完了の結果が0行であることです。18.9以降なら sudo gitlab-rake gitlab:background_migrations:list、18.8以前なら gitlab:background_migrations:status で一覧も見られます。いきなり本番に流さず、本番を複製した検証環境で各段の所要時間を測ってから本番の作業時間帯を決めます。
Runnerを止めてジョブの受付を止めるNGINX設定と作業後の戻し方
アップグレード中にRunnerがジョブを処理していると、トレースの更新や成果物のアップロードが失敗します。公式は、Runnerを一時停止したうえで、ジョブ取得のAPIに503を返す設定を入れる方法を示しています。
# /etc/gitlab/gitlab.rb に追記してから sudo gitlab-ctl reconfigure
nginx['custom_gitlab_server_config'] = "location = /api/v4/jobs/request {\n deny all;\n return 503;\n}\n"実行中のジョブがすべて終わるのを待ってからパッケージを入れ替えます。すべての段が終わったら、この行を消して再度 reconfigure する操作と、Runnerの再開が必要です。Runner自体の版をGitLab本体にそろえる手順やexecutorごとの設定はGitLab Runnerとは：executorの選び方と登録手順にまとめています。
アップグレード後に確かめる6項目と同じ版のバックアップで戻す手順
各段の完了後と最終段の完了後に、事前チェックの5コマンドをもう一度流し、画面とCI/CDで次の6項目を確かめます。
- サインインでき、プロジェクト一覧・Issue・マージリクエストが開ける
- リポジトリのクローンとpushができる
- Runnerがジョブを取得して完了させる
- コンテナレジストリへのイメージのpushとpullができる
- Elasticsearchを使っている場合は検索が返る
- 管理エリアの「Database pre-upgrade checks」でSchema health checkと検索パス（search_path）が正常
戻す場合の条件は厳しいので先に把握しておきます。ロールバックの手順は、戻し先とまったく同じ版・同じエディションで取ったデータベースのバックアップを必須としています。パッケージを古い版に入れ直すだけでは、新しい版で変わったスキーマは戻りません。停止点ごとにバックアップを取っておけば、失敗した段の直前まで戻れます。
停止点を経由するアップグレードの運用判断｜四半期運用・回数・委託の条件
手順が分かっても、いつ・どこまで上げるかを決めないと版は溜まります。ここでは環境の条件ごとに判断を言い切ります。
3か月ごとの停止点に合わせて四半期に1度上げる運用を採用する条件
単一ノードのLinuxパッケージかDocker構成で、検証環境を用意できるチームは、四半期に1度、最新の停止点まで上げる運用を採用します。マイナー版が毎月出るので、停止点は3か月おきに来ます。19.2が2026年7月、19.5が10月に出ており、毎月第3木曜の周期どおりなら次の停止点19.8は2027年1月です。四半期ごとに上げれば毎回1段で済み、読むアップグレードノートも3か月分です。
毎月上げる運用は、この規模では手間に見合いません。セキュリティの修正版は保守対象の3つのマイナー版すべてに出るため、四半期の合間はパッチ版の適用で足ります。脆弱性が出たときに修正版を選ぶ手順はGitLab脆弱性の対応手順で扱っています。
複数ノードのゼロダウンタイム更新は1マイナーずつで回数が増える
止められない業務でHA構成を組んでいる場合は、通常の経路とは異なる作業回数の見積もりが必要です。ゼロダウンタイムでのアップグレードは、1回の更新で上げられるのはマイナー版1つまで（16.1から16.2へは可、16.3へは不可）と定めています。停止点だけを踏む通常の経路と違い、途中の全マイナー版を1つずつ通ります。18.4から18.11までだけでも7回です。
この構成で1年溜めると、作業は12回前後に膨らみます。ゼロダウンタイムを前提にするなら、毎月上げる運用を選ばないと計画が回りません。PostgreSQLのメジャー版の更新はゼロダウンタイムの対象外なので、19.0のPostgreSQL 17要件は別の停止時間を取って処理します。
担当者が兼務で停止点を2つ以上溜めた環境の更新を外部へ委ねる判断基準
停止点を2つ以上溜めていて、GitLabの担当者が他業務との兼務1人という環境は、自社で上げ切る計画を見送ります。経由が3段を超えると、PostgreSQL・OS・Redisの前提変更が経路上に重なり、ロールバックの判断も段ごとに必要になります。1段の失敗が業務停止に直結するのに、検証環境を作る工数が取れないからです。
この場合は、検証環境での通し実行とロールバック手順の作成までを含めて外部に委ね、以後の四半期運用をどちらが持つかを契約で決めます。一創では保守運用・内製化支援として、Self-Managed GitLabのような自社管理基盤の更新作業の代行と、手順書を残して社内で回せるようにする支援を受けています。
よくある質問：GitLabのアップグレードパスと経由版で迷う5つの論点
GitLabのアップグレードパスについて、計画を立てる段階でよく出る疑問をまとめます。
GitLab.comを使っている場合もアップグレードパスを気にする必要はありますか？
必要ありません。GitLab.comはGitLab社が運用しており、利用者が版を上げる操作はありません。アップグレードパスと停止点が関係するのは、自社サーバーやクラウド上で動かすSelf-Managedの利用者です。ただし、自社で管理しているGitLab Runnerの版はGitLab.comでも利用者の管理なので、Runnerの更新は別に計画します。
停止点を飛ばして最新版を直接入れるとどうなりますか？
経路に停止点が残っている状態では、公式ドキュメントのとおり最新のメジャー版へ直接は上げられません。パッケージのインストール時に前提チェックで止まる場合があり、止まらなかった場合でも、前の版のバックグラウンドマイグレーションが終わっていないデータに新しい版の移行が走り、失敗の原因になります。停止点はひとつずつ経由します。
停止点ではどのパッチ版を選べばよいですか？
そのマイナー版でリポジトリにある最新のパッチ版を選びます。公式も最初のパッチではなく最新パッチを入れるよう勧めています。18.11.0・18.11.1のように特定の環境で避けるよう明記された版もありますが、最新パッチを選ぶ限り踏むことはありません。Upgrade Path toolが表示する版も、その時点の最新パッチです。
バックグラウンドマイグレーションの完了にはどれくらいかかりますか？
データ量と版によって数分から数日まで幅があり、公式に目安の時間は示されていません。プロジェクト数やCIの実行履歴が多いインスタンスほど長くなります。本番を複製した検証環境で各段を実行して所要時間を測り、その結果から本番の作業日程を組むのが確実です。
Docker版やHelmチャート版でもアップグレードパスは同じですか？
経由する停止点は同じです。違うのは作業の方法で、Docker版はイメージタグを停止点の版に書き換えて起動し直し、Helmチャート版はGitLabの版に対応するチャートの版を選んで更新します。どちらも各段でバックグラウンドマイグレーションの完了を待つ点は、Linuxパッケージ版と変わりません。
関連記事
- GitLabとは：構成要素・CEとEEの違い・3つの提供形態とDockerで試す手順：Self-ManagedとGitLab.comの違いを先に整理できます
- GitLab 19.2とは？Duo CLI・カスタムフローGAで変わる開発運用：停止点19.2で入る機能と変更点を確認できます
- GitLab CI/CDとは：.gitlab-ci.ymlの書き方とrules・needs・変数の設定例：アップグレード後のCI/CDの動作確認に使うパイプラインの書き方です
- GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較：Self-Managedを続けるか見直すときの比較材料になります
