Artifact Registry と Organizations のインターフェース合意

概要

Artifact Registry (AR) は、最初の組織レベルの GitLab 機能です。Organizations は AR のデータパーティショニング、ストレージ、ビリング、アクセス制御のアンカーポイントです。ここで行われる意思決定は、将来の組織レベル機能の前例となります。

本ドキュメントでは、AR と Organizations の間のインターフェース合意を定義します。AR が必要とするもの、AR が提供するもの、未解決の質問を明確にします。議論は時間や媒体を越えて行われ、関係者全員が容易に追跡できるとは限りません。他の場所で行われた関連する決定は、本ドキュメントで記録・承認されるまでは認識されておらず受け入れられてもいないものとします。

バージョン履歴

タイムライン

AR は、Q2 FY27 末（2026 年 7 月 31 日）までに .com での公開を目指しています。Self-Managed と Dedicated のオンボーディングは Q2 ローンチのスコープ外で、Q3/Q4 FY27 にターゲットされている統一セルフサービスオンボーディングワークフローに依存します。Organizations チームは、Q2 の Organization GA をスコープダウンし、AR ローンチに必要な要素のみに絞りました。すなわち、AR 有効化前の Organization 確認、サイドパネル内の Organization オブジェクト、シェルランディングページ（Organization オブジェクト配下の最小ページで、AR が独自のビューで埋める）です。管理エリア、設定、オーナー判定、ユーザー管理は先送りされています。

本ドキュメントの MUST 要件は、AR が顧客のオンボーディングを開始する前に満たされる必要があります。

要件レベル

本ドキュメントでは RFC 2119 のキーワードを使用します。MUST、MUST NOT、SHOULD、SHOULD NOT、MAY が要件レベルを示します。

用語

Organization 要件

AR は組織のメンバーシップ、階層、ライフサイクルを解釈しません。AR は namespace 作成時に organization_id を受け取り、アンカータプルに保存します。それ以降、AR は organization_id を不透明な値として扱います。AR は他のすべての組織プロパティ（名前、パス、メンバーシップ、設定、プラン）を無視します。

組織 ID や属性は AR の公開 API や URL に出現しません。organization_id は厳密に内部的なもので、ビリング按分に使われますが、クライアントには露出しません。

AR が提供するもの

可用性

AR は、namespace を作成する前に、すべてのインストールタイプで Organization を必要とします。

TLG 移管

Organizations チームの最終的な計画では、すべての .com TLG を独自の Organization に移管します（1:1）。Organization は TLG を含み、置き換えたり再構成したりはしません。複数の TLG を所有する顧客は、これらの自動プロビジョンされた Organization を後でまとめられるようになります。AR はこのマッピングを規定しません。

確認

AR は未確認の Organization で MUST NOT 有効化されてはいけません。確認は Rails 側で強制されます。namespace 作成 API は、Organization が確認済みになった後にのみ呼ばれる MUST ものとします。AR は呼び出し元を信頼し、自身では確認チェックをスキップします。

ID 安定性

UI 配置

ビリングとエンタイトルメント

ビリングは #591904 で詳細に扱われています。プロビジョニングパイプライン（設計）と利用トラッキング（提案）は Fulfillment チームが所有しており、Organizations チームではありません。以下は、Organizations と交差するビリング前提条件です。

ユーザーメンバーシップ

ユーザーは複数の Organization のメンバーになれます（organization_users 結合テーブル経由）。各 AR リクエストは単一の namespace（および 1 つの Organization）にスコープされます。1 つのリクエストが複数の Organization にまたがることはできません。パブリックリポジトリは Organization メンバーシップなしでもアクセス可能です。非分離 Organization はユーザークレームステップを必要としません。ユーザー／アカウント移行は分離バージョン（将来的）にのみ適用されます。

組織マージ

注: このセクションは、要件を最終決定する前に問題空間について両チームが共通の理解を持つ必要があるため、本ドキュメントの他のセクションよりも深く踏み込みます。合意後、主要な要件は Organization 要件 に統合され、AR 固有の設計詳細は別ドキュメントに移されます。

組織マージは直近のロードマップにはありません（Merge Tooling epic）。それでも、アーキテクチャはマージを構造的に不可能にしては MUST NOT ならず、マージを促進する MUST 必要があります。

現在のアーキテクチャでは、両方の Organization が AR を有効化している場合に 2 つの Organization がマージされると、生き残った Organization が 2 つの namespace を持つことになります。2 つの namespace は重複データ（二重請求）、重複構成、アーティファクトの統一ビューがないことを意味します。組織あたり 1 つの namespace が唯一望ましい 目標 状態です。

初期リリースには、予防ゲート（例: 各顧客の AR 有効 Organization を 1 つに制限）と マージブロッキング要件（後述）で十分です。中長期的には、計画外または自然発生的な組織マージは避けられず、予測不能な頻度で発生するため、エンジニアの介入なしに MUST 処理される必要があります。

マージトリガー

2 つの Organization がマージされると、一方が生き残り、もう一方が吸収されます。AR の視点では、即時のアクションはアンカータプルの更新です。吸収される側の namespace の entity_id を生き残った organization_id を指すように更新します。これは namespace ごとに 1 行の更新です。データは移動しません。

Namespace Decoupling ADR は、すべてのデータを organization_id ではなく namespace にスコープすることでこれを可能にします。この間接化がない場合（つまり AR が直接 organization_id に紐づいている場合）、このステップでさえ完全なデータマイグレーションが必要になります。

マージシナリオ

結果は、どの Organization が AR を有効化しているかによって異なります。

1. 生き残った Organization のみ AR を有効化: 何も変わりません。namespace はすでに生き残った Organization を指しています。
2. 吸収される Organization のみ AR を有効化: アンカータプルが更新され、生き残った Organization を指します。すべてのデータが namespace にスコープされている（organization_id ではなく）ため、データマイグレーションは不要です。namespace、スラグ、すべてのデータは変更されません。1:1 が保たれます。
3. 両方の Organization が AR を有効化: 生き残った Organization は 2 つの namespace を持ちます。これは下記のnamespace 統合 の遷移状態に入ります。

初期フェーズ: ブロッキング

下記の namespace 統合ツールとマルチ namespace UX は、現時点では存在しません。これらが利用可能になるまで、両方の Organization が AR を有効化している組織マージは MUST ブロックされる必要があります。対応する UX とツールなしにマージを許可すると、顧客は見ることも、制御することも、解決することもできない状態に陥ります。

Namespace 統合

1:N 状態は 遷移的 で SHOULD あるべきで、永続的ではありません。ただし提案する統合は顧客主導であるため、その状態が続く限り収束を強制することはできません。1:1 が望ましい 目標 状態であることに変わりはありません。それでも、1:N 状態は MUST 管理 される必要があります。顧客は、両方の namespace の可視性とマイグレーション制御を持ち、自分のペースで 1:1 に収束できる必要があります。サポートを拒否すると、組織マージを無期限にブロックするか、顧客もプラットフォームも安全にスケールで運用できない破壊的で不透明なデータマイグレーションを強制することになります。

なぜデータマイグレーションが必要か

AR は namespace 単位でデータをパーティショニングし、ストレージを重複排除しています。境界によってデータをスコープするシステムは、境界が変わるときにそのデータをレコンサイルする必要があります。2 つの namespace が 1 つになると、パーティション化されたデータと重複排除コンテキストを統合する必要があります。これは、アンカーエンティティが何（Organization、トップレベルグループ、その他の境界）であっても真です。namespace 抽象は、Organization が変わるとき AR をデータマイグレーションから守ります（シナリオ 2）。データマイグレーションは、顧客が 2 つの namespace を 1 つに統合したいときにのみ必要です（シナリオ 3）。それは 1:1 の目標状態によって駆動され、マージイベントそのものではありません。

マルチ namespace UX

利用可能になった時点で、マルチ namespace の UX は最低限以下を MUST 提供する必要があります。

• Namespace 一覧: Organization 配下のすべての namespace と、namespace ごとの使用量・ビリング。
• Namespace ごとのリポジトリ参照: どれを移動するか判断するため、各 namespace を独立してナビゲート。
• マイグレーション制御: ある namespace から別の namespace へリポジトリを移動。
• ビリング可視性: Namespace ごとのストレージと使用量、2 つの namespace をアクティブに保つコストを顧客が理解できるように。

以下の図は概念のみを示します。UX を規定するものではありません。2 つの状態でナビゲーション構造がどう異なるかを示します。

1:1（目標状態）: Organization の単一 AR namespace はバックエンドに存在しますが、UX は隠しています。リポジトリは Artifact Registry ランディングページの直下に一覧されます。

┌─ Organization: Acme Corp ───────────────────────────┐
│                                                     │
│  Artifact Registry                                  │
│  ┌─────────────────────────────────────────────┐    │
│  │ namespace: acme-eng (hidden from UX)        │    │
│  │                                             │    │
│  │  ├── acme-eng/my-app                        │    │
│  │  ├── acme-eng/platform-lib                  │    │
│  │  ├── acme-eng/service-a                     │    │
│  │  └── ...                                    │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

1:N（マージ後遷移状態）: Acme Corp が別の Organization を吸収し、acme-platform AR namespace を持ち込みました。これは元の acme-eng namespace と並んで存在します。Namespace はナビゲーションレベルとして表面化されます。各 namespace は独自のリポジトリ、アクセスルール、ビリング、マイグレーション制御を持ちます。

┌─ Organization: Acme Corp (merged) ──────────────────┐
│                                                     │
│  Artifact Registry                                  │
│  ┌─────────────────────────────────────────────┐    │
│  │ ▸ acme-eng              3 repos    1.2 GB   │    │
│  │ ▸ acme-platform         2 repos    0.8 GB   │    │
│  └─────────────────────────────────────────────┘    │
│                                                     │
│  ▾ acme-eng (expanded)                              │
│  ┌─────────────────────────────────────────────┐    │
│  │  ├── acme-eng/my-app                        │    │
│  │  ├── acme-eng/service-a                     │    │
│  │  └── ...                                    │    │
│  │                                   [Migrate] │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

マイグレーションアプローチ

namespace 統合は MUST 顧客主導である必要があります。自動化された一括マイグレーションを使っては MUST NOT いけません。各顧客のデータレイアウト、クライアント構成、運用上の制約は異なります。.com コンテナレジストリのマイグレーションは、大規模な自動オンラインマイグレーションが成功し得ることを示しましたが、慎重にオーケストレーションされた一回限りのイベントとしてのみでした。組織マージは繰り返し発生するセルフサービス操作であり、別のアプローチが必要です。

検討中のメカニズムは 2 つあります（相互排他的ではありません）。

• 顧客主導マイグレーション: 顧客は、GitLab が提供するツールを使って、自分のペースで namespace 間にリポジトリを移動します。
• 自動レイジーマイグレーション: クライアントアクセス時にリポジトリを生き残った namespace に透過的に移行します。

MVP 後に AR が他のプロバイダーからアーティファクトをインポートするために提供するマイグレーション機能の一部を再利用する機会がある MAY かもしれません。データマイグレーションの内部詳細は本ドキュメントのスコープ外です。

ソース namespace が空になったら、それは SHOULD 廃止され、そのスラグは生き残った namespace のエイリアスに MUST なる必要があります。両スラグはリダイレクトなしで同じ namespace に解決します。顧客は、すべてのクライアントが生き残ったスラグの URL に移行した後、エイリアスを 永久に 無効化できる SHOULD ようにすべきです。セキュリティ上の理由から、古いクライアント設定が別の顧客の namespace に解決するのを防ぐため、スラグは無期限に予約されたままで MUST あるべきです。

マルチ namespace シナリオの予防

関連するが別の懸念は予防です。顧客が複数の AR 有効 Organization を持つ可能性をそもそも 減らす 方法です。顧客が Organization を確認し AR を有効化する順序が重要です。

1. 顧客は TLG-A と TLG-B を持っています。
2. 各 TLG はそれぞれ独自の Organization に移管されます。
3. 顧客は両方の Organization で AR を有効化します。それぞれが独自の namespace を取得します。
4. すぐ後、2 つの Organization がマージします。生き残った Organization は今や 2 つの namespace を持っています。

マージトリガー と namespace 統合 のセクションでは、これが発生したときに何が起こるかを扱います。ここでの懸念は、その状態に至る可能性を減らすことです。

.com 顧客のうち複数の TLG を持つのはわずか約 2.7% です（ソース）が、この数字はおそらく問題を過小評価しています。なぜなら、すべての .com 顧客にわたって平均しているのに対し、エンタープライズ顧客（AR の主要採用ターゲット）は複数の TLG を持つより複雑な組織構造を持つ傾向があるためです。SM/Dedicated は影響を受けません（単一 Organization、ID=1）。リスクは AR 採用が最も重要な .com エンタープライズ顧客に集中します。

予防ゲート

未解決の質問

提案する進め方

このセクションは、上記の要件を段階的なロールアウトに並べたものです。各フェーズは前のフェーズの上に構築されます。各項目は、前のセクションで定義された要件、制約、または根拠に遡ります。最初にそれらを読むことが不可欠です。

フェーズ 0: ローンチ前

目標: 2026 年 6 月末

AR が顧客のオンボーディングを開始する前に、以下の項目に対処する必要があります。

フェーズ 1: ローンチ（MVP）

目標: Q2 FY27 末（2026 年 7 月）

AR は .com で顧客のオンボーディングを開始します。SM と Dedicated のオンボーディングは、統一セルフサービスオンボーディングワークフローが利用可能になるまで先送りされます（Q3/Q4 FY27）。

フェーズ 2: namespace 統合

目標: TBD

2 つの AR namespace を 1 つに収束させるツールと UX を提供することで、マージブロッカーを解除します。

関連

AR アーキテクチャ決定事項:

• Organizations as Anchor Point ADR
• Namespace Decoupling ADR

Organizations アーキテクチャ決定事項:

• SM/Dedicated Single Organization ADR
• Organization transfer support (database dictionary)

インターフェース合意:

• AR/Infrastructure
• AR/Auth

GitLab issue と epic:

• Non-Isolated Organizations: User Onboarding & AR Enablement
• Organization and TLG Reconciliation (Merge Tooling)
• CustomersDot: Service Onboarding and Slug Registration
• Licensing, Billing, and Provisioning
• Slug Validation Rules and Reservation Policy
• User-facing Name for Namespace Entity

主要なコメント:

• Q2 descoped onboarding summary (2026-04-02)
• TLGs vs Organizations clarification (2026-04-01)

その他の参考資料:

• Organizations: MVP Launch Requirements meeting notes (2026-04-08)
• CTO Module Review
• CTO Review Notes
• Onboarding and merging POC demo
• Reconciliation POC demo
• Organization sidebar POC demo
• Organization Landing Page UX alignment notes
• Organization Landing Page and AR design (Figma)
• Org/AR user flow design (Figma)

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