GitLab リリースマニフェスト

概要

GitLab リリースマニフェストは、特定の上位 GitLab バージョンと互換性がある GitLab のモジュール式コンポーネントのバージョンに関する構造化データを提供します。この情報は、GitLab Orbit や Artifact Registry などのモジュール式コンポーネントを含む GitLab 環境を提供することを目的とした、社内外のインストールツールで使用されることを想定しています。リリースマニフェストは、（モジュール式コンポーネントを含む）GitLab の初回インストールと、GitLab を自動的にアップグレードする際の体験を簡素化することに特に重点を置いて構築されています。

ゴール、非ゴール、前提条件

ゴール

1. GitLab バージョンと互換性があるモジュール式コンポーネントのバージョンを伝える
2. モジュール式コンポーネントのリリースサイクルが、GitLab の現在のリリーススケジュールに左右されないようにする
3. GitLab インストールの大部分を変更せずに、単一のモジュール式コンポーネントをアップグレードできるようにする
4. リリースマニフェストを構造化し、機械可読にする
5. GitLab バージョンの公開後は、リリースマニフェストを不変にする

非ゴール

1. Managed versioning を置き換える
2. GitLab Rails コードベース内の *_VERSION ファイル（GITLAB_KAS_VERSION、GITALY_SERVER_VERSION など）を置き換える
3. モジュール式コンポーネントのバイナリ、Docker イメージ、Helm チャートをビルドしたり、既存の GitLab Helm チャート、CNG イメージ、Omnibus パッケージにバンドルしたりする

前提条件

1. モジュール式コンポーネントはセマンティックバージョニングに従い、Release Framework を使用してセマンティックリリースを生成する
2. モジュール式コンポーネントは、バイナリ、コンテナイメージ、Helm チャートなどの独自のビルドアーティファクトをビルドする
3. モジュール式コンポーネントは、それぞれのペースでリリースにタグを付けて公開する

現在の状態

各 GitLab バージョンは、Rails コードベース以外にも多くのコンポーネントで構成されています。これらのコンポーネントのバージョンを保存するために一般的に使用されている方法は、**Rails コードベースに *_VERSION ファイルを追加することです。**この方法は現在、Gitaly、KAS、Pages、Shell、Zoekt、OpenBao などで使用されています。

このバージョンファイルはさまざまな方法で更新されます。OpenBao では手動、Zoekt では Renovate Bot を使用して更新されます。また、リリースツールを使用する更新は、Managed Versioning の対象コンポーネント（Gitaly と KAS）で行われます。

Release Framework を使用して独自のリポジトリからビルド、リリースされる新しいモジュール式コンポーネントが、数十個の規模で急速に追加されると予想しています。このシナリオでは、新しいモジュール式コンポーネントごとに Rails コードベースへ *_VERSION ファイルを導入し、保守することは現実的ではなくなります。リリースマニフェストは、Release Framework が提供する標準化を基盤として、バージョン管理を簡素化することを提案します。

提案するソリューション

リリースマニフェストは、GitLab リリースが公開されるたびに、各モジュール式コンポーネントの互換バージョンのスナップショットを取得し、ほかのツールが利用できるよう機械可読形式で保存します。特定の GitLab バージョンから、その GitLab バージョンで動作するすべてのモジュール式コンポーネントの互換バージョンへのマッピングを提供します。

flowchart LR
    MCR[Modular Component - Release published] -->|Component entry updated in the Mutable catalog| RMMut[(Mutable Catalog)]

    GRS[GitLab Release Schedule] -->|GitLab monthly or weekly scheduled release published| GRP[GitLab Release Published]

    GRP ==> |Release manifest frozen for the current milestone| RMMut
    GRP ==> |Release manifest initialized for the next milestone| RMMut

    subgraph RM[Release Manifest]
        direction TD
        RMMut

        RMMut ==>|Release manifest frozen for the current milestone| RMImmut[(Immutable Record)]

        RMImmut
    end

    linkStyle 2 stroke:red
    linkStyle 3 stroke:blue
    linkStyle 4 stroke:red

これには、次の 2 つが含まれます。

1. 将来の GitLab リリースに対応する互換バージョンの可変カタログ: このカタログは Release Framework 内の CI ジョブを使用して自動的に更新されるため、モジュール式コンポーネントを開発するチームの介入は必要ありません。Release Framework ではコンポーネントがセマンティックバージョニングに従う必要があるため、すべての Release Framework コンポーネントがデフォルトで可変カタログに含まれます。
2. 過去の GitLab リリースに対応する互換バージョンの不変レコード: GitLab リリースがユーザーに公開されると、そのリリースのカタログエントリが不変ストアにコピーされます。これは、将来の任意の時点でこのバージョンをインストールしようとするすべてのツールの参照情報となります。

データモデル

可変カタログ

今後の GitLab リリース 19.5.0 に対応する artifact-registry のリリースマニフェストエントリは、ファイル 19/5/0/artifact-registry.json 内に置かれます。文字列 artifact-registry は、Release Framework 内でのモジュールの ID です。リリースマニフェストでは、これを識別子として使用します。

エントリの内容は次の形式になります。

{
  "version": "1.275.1",
  "sha": "6cdaf83c809b7d02c794d5db2dea9e101c662ac7",
  "ref": "v1.275.1",
  "source": {
    "url": "https://gitlab.com/gitlab-org/ops/artifact-registry"
  }
}

同様に、knowledge-graph（GitLab Orbit）のエントリは、ファイル 19/5/0/knowledge-graph.json 内に置かれ、次の内容になります。

{
  "version": "0.95.3",
  "sha": "51aab3662a8764f47616acefdff8163312bd2bc6",
  "ref": "v0.95.3",
  "source": {
    "url": "https://gitlab.com/gitlab-org/orbit/knowledge-graph"
  }
}

このようなエントリは、コンポーネントのうち、Release Framework を使用して管理されるすべてのものに存在します。

可変カタログは、モジュール式コンポーネントのバージョンがユーザーに公開された後にのみ更新されます。これにより、モジュール式コンポーネントチームは、コンポーネントのバージョンを包括的な GitLab バージョンに含めるタイミングを制御できます。

不変レコード

リリース 19.5.0 がユーザーに公開されると、複数のコンポーネントのバージョン情報を単一のファイル 19/5/0.json に統合します。このファイルの内容は次の形式に従います。

{
  "version": "19.5.0",
  "modules": {
    "artifact-registry": {
      "version": "1.275.1",
      "sha": "6cdaf83c809b7d02c794d5db2dea9e101c662ac7",
      "ref": "v1.275.1",
      "source": {
        "url": "https://gitlab.com/gitlab-org/ops/artifact-registry"
      }
    },
    "knowledge-graph": {
      "version": "0.95.3",
      "sha": "51aab3662a8764f47616acefdff8163312bd2bc6",
      "ref": "v0.95.3",
      "source": {
        "url": "https://gitlab.com/gitlab-org/orbit/knowledge-graph"
      }
    }
  }
}

保存先

リリースマニフェストは、gitlab-org/release/manifests 配下の 3 つの専用プロジェクトに置かれています。モジュールの作成者と利用者は、ここから確認してください。

どちらのデータプロジェクトでも、人が main に直接プッシュすることはありません。main のプッシュ許可リストには、リリース自動化ボットだけが登録されています。人が行う変更はマージリクエストを経由する必要があり、そこで CI チェックによって取り込みの可否を判定します。両プロジェクトとも、すべてのファイルをスキーマに照らして検証します。さらに、レコードのプロジェクトでは既存のレコードファイルを変更するマージリクエストを失敗させることで、「公開後は不変」というゴール（ゴールを参照）を慣例ではなく仕組みで強制します。意図的な訂正は引き続き可能です。その場合は record-change-approved ラベルが必要で、ラベルがあればジョブは成功し、変更したファイル名を示す監査コメントを投稿します。

エントリの書き込み方法

リリースマニフェストへの書き込みは、別々の 2 つのイベントによって、それぞれ異なるプロジェクトに対して行われます。

モジュールのバージョンが公開されるとき。 release-tools が、今後公開予定の GitLab バージョンごとに、そのモジュールのエントリを可変カタログに追加します。書き込みは GitLab のリリースを待たず、他のモジュールにも影響しません。これにより、モジュールのリリースサイクルを GitLab のリリーススケジュールから独立させます（ゴールを参照）。

GitLab のバージョンが公開されるとき。 release-tools が、そのバージョンのカタログエントリを不変レコードの 1 つのファイルに固定し、同じエントリを次のバージョンのカタログに引き継ぎます。それ以降、その固定されたファイルが当該 GitLab バージョンの参照情報となり、変更されることはありません。

エントリを引き継ぐことで、モジュールが再び公開されるまで、最後に公開されたバージョンをカタログ内に保持します。リリース頻度の低いモジュールも後のレコードに引き続き含まれ、サイクル中にモジュールが公開された場合は、そのエントリが置き換わります。

関連ドキュメント

1. GitLab R&D Summit 2026 - Release Manifest Demo（GitLab Delivery）- Google Slides
2. デモで使用したリポジトリとコンテンツ。保存先に示した本番プロジェクトに置き換えられています
   1. 可変カタログ
   2. 不変レコード
3. 実装の詳細とコンポーネントの変更

ページのソースコードを見る - ページの編集 - please contribute.