Content last updated 2026-04-08

グループとプロジェクトの操作と状態管理

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.
StatusAuthorsCoachDRIsOwning StageCreated
ongoinglohrc rymailohrc rymai abdwdddevops runtime2025-05-26

概要

このブループリントは、GitLab ネームスペース（グループとプロジェクト）のための統一状態管理およびトラッキングシステムと、状態に関連する操作を非同期にするためのガイドラインを提案します。現在、グループとプロジェクトは状態管理（削除、アーカイブ、移転）を、一貫性のないデータ表現と履歴追跡なしに別々の機能として実装しています。提案されているソリューションは、namespaces.state と namespace_details.state_metadata を使用した一元化された状態管理システムを導入し、すべてのネームスペースタイプにわたって一貫した状態トラッキング、メタデータストレージ、履歴レコードを提供します。

モチベーション

グループとプロジェクトには現在、いくつかの問題を引き起こす一貫性のない状態管理実装があります：

現在の問題点：

  • グループの状態管理に一貫性がない
  • プロジェクトの状態管理に一貫性がない
  • グループとプロジェクトの状態管理間に一貫性がない
  • 子孫の状態が祖先から一貫性なく推論されることがある
  • 状態変更の監査証跡がない。例えば、プロジェクトがアーカイブされてからアーカイブ解除された時期、またはグループが別のネームスペースから移転された時期を知ることが不可能
  • 同様の操作に異なるデータモデルが使用されている（例：「削除スケジュール済み」状態を追跡するための group_deletion_schedules vs projects.marked_for_deletion_at）
  • 長時間実行される同期操作によるパフォーマンス問題（99.95 パーセンタイル：グループ移転 51 秒、プロジェクト移転 27 秒）

ビジネスへの影響：

  • 一貫性のない動作とバグによるユーザー体験の低下
  • タイムアウトを引き起こすパフォーマンスボトルネックによるユーザー体験の低下
  • タイムアウトやバグにより失敗した操作を解決するためのサポートおよびエンジニアリングチームへの負荷増大
  • 監査とコンプライアンスの困難
  • 重複した一貫性のないコードによるメンテナンスオーバーヘッド

目標

  • すべてのネームスペースタイプのための統一状態管理システムを確立する
  • グループとプロジェクト全体で一貫した API と動作を提供する
  • 状態変更の監査証跡を可能にする
  • 適切な操作を非同期にすることでパフォーマンスを向上させる
  • メタデータトラッキングをサポートする（アクションの開始者、エラー状態、継承）
  • コードの重複とメンテナンスオーバーヘッドを削減する
  • より良い観測可能性とデバッグ機能を可能にする

非目標

  • 既存機能の完全な書き換え（段階的な移行アプローチ）
  • 初期実装でのユーザー向け API または UI の変更
  • 状態に関係しないグループ/プロジェクト統合作業の移行
  • 状態管理に関係しないパフォーマンス最適化

提案

一元化されたネームスペース状態管理システムと非同期操作ガイドラインを導入します。

状態管理データアーキテクチャ

001: 統一状態管理システム を参照してください。

非同期操作ガイドライン

002: 非同期操作ガイドライン を参照してください。

移行戦略

005: 移行戦略と後方互換性 を参照してください。

パフォーマンスに関する考慮事項

非同期操作：

  • グループ移転（P1 優先度 - 現在 99.95 パーセンタイルで 51 秒）
  • プロジェクト移転（P1 優先度 - 現在 99.95 パーセンタイルで 27 秒）

最適化戦略：

  • 子孫に状態を伝播させることで高速読み取りを実現し、読み取り時の祖先ルックアップを排除
  • state および関連カラムへのデータベースインデックス

メトリクスと成功基準

パフォーマンスターゲット：

  • P99.95 グループ移転時間を 51 秒から <10 秒に削減
  • P99.95 プロジェクト移転時間を 27 秒から <5 秒に削減
  • 削除操作のパフォーマンスを維持（スケジューリングで <2 秒）

品質メトリクス：

  • 完全移行後の状態不整合バグをゼロに
  • 状態変更に対する 100% の監査イベントカバレッジ
  • すべてのネームスペースタイプにわたる統合テストカバレッジ

開発者体験：

  • すべての状態管理操作のための単一 API
  • 一貫した動作ドキュメント
  • コード重複の削減（状態関連コードを 50% 削減目標）

決定事項

リスクと軽減策

リスク：データ移行の複雑さ

  • 軽減策： ロールバック機能を備えた段階的アプローチ、徹底的なテスト

リスク：移行中のパフォーマンス影響

  • 軽減策： カーソルベースの DFS を使用したツリーイテレーターによるバッチ伝播、機能フラグ、監視

リスク：API の破壊的変更

  • 軽減策： 後方互換性の維持、バージョン管理された API

リスク：状態の一貫性問題

  • 軽減策： 移行期間中の双方向同期、バリデーションチェック
グループとプロジェクト操作 ADR 003: 状態伝播モデル
コンテキスト GitLab の階層的なネームスペース構造（Organization > Group > Subgroup > Project）において、状態管理は継承を効率的に処理す …
グループとプロジェクト操作 ADR 001: 統一状態管理システム
コンテキスト 設計ドキュメントの現在の問題点セクションに詳述されているように、グループとプロジェクトは現在、ユーザー体験の低下、サポート負担の増大、監査とコンプライアンスの困難、および重複コードによる …
グループおよびプロジェクト操作 ADR 006: 状態の保存
コンテキスト 状態遷移を実行する際、特にキャンセルや障害回復のシナリオでは、システムは遷移が発生する前に名前空間がどの状態にあったかを記憶する必要があります。この機能がなければ、操作を逆転させる際に重 …
グループおよびプロジェクト操作 ADR 004: 状態変更の監査統合
コンテキスト グループとプロジェクトは現在、状態変更の監査証跡を持っていません（プロジェクトがアーカイブされ、その後アーカイブ解除された時期や、グループが転送された時期を知ることができません）。 これ …
グループおよびプロジェクト操作 ADR 005: 移行戦略と後方互換性
コンテキスト 現在の一貫性のない状態管理システムから統一状態管理システムへの移行には、以下を確保するための慎重な計画が必要です: 移行中のゼロダウンタイム 既存の API およびユーザーインターフェー …
グループとプロジェクト操作 ADR 002: 非同期操作ガイドライン
コンテキスト 現在のグループとプロジェクトの操作は重大なパフォーマンス問題に悩まされています： グループ移転：P99.95 パフォーマンスが 51 秒 プロジェクト移転：P99.95 パフォー …
最終更新 July 30, 2026: Merge pull request #483 from kyama0/translation/batch-2026-07-29-1 (c955a93f)
ページのソースコードを見る - ページの編集 - please contribute. Creative Commons License