GitLab Orbit Remoteの仕組み

インデックス作成パイプライン

GitLab Orbitは2つのソースからデータをインデックス作成し、単一のグラフに統合します。

SDLCデータ

GitLabは変更データキャプチャ（CDC）パイプラインを通じて変更イベントをストリーミングし、GitLab Data Insights Platformに送信します。このプラットフォームはClickHouseテーブルにレコードを書き込み、GitLab OrbitはそのデータをもとにグラフをClickHouse上に構築します。

この処理は継続的に行われます。ユーザーがマージリクエストを作成したり、作業アイテムを作成したり、パイプラインを起動したりすると、その変更は数分以内にGitLab Orbitグラフに反映されます。

ソースコード

GitLab OrbitはGitLab Rails内部APIを呼び出し、リポジトリからソースファイルをフェッチします。各ファイルを言語固有のパーサーで解析し、定義（関数、クラス、モジュール）とインポート参照を抽出して、ノードとエッジとしてグラフに書き込みます。

コードはデフォルトブランチのみからインデックス作成されます。デフォルトブランチが変更されると、再インデックス作成が自動的に実行されます。

グラフの構築

SDLCデータとコードを読み込んだ後、GitLab Orbitは統合グラフをClickHouseに書き込みます。各エンティティ（プロジェクト、ユーザー、関数定義）はノードになります。各リレーションシップ（ユーザーがマージリクエストを作成した、ファイルがモジュールをインポートしたなど）は有向エッジになります。

クエリを送信すると、GitLab OrbitはJSON クエリDSLをClickHouse SQLにコンパイルして実行し、型付きの結果を返します。

グラフモデル

グラフには2つのレイヤーがあります:

• SDLCレイヤー: GitLabオブジェクトとそのリレーションシップ。プロジェクトはグループに属します。ユーザーはマージリクエストを作成します。パイプラインはプロジェクト上で実行されます。作業アイテムはユーザーに割り当てられます。
• コードレイヤー: ソースコードの構造とクロスファイル参照。関数はファイル内で定義されます。ファイルは他のファイルからシンボルをインポートします。定義はプロジェクトとブランチ内に存在します。

この2つのレイヤーは連携しています。マージリクエスト（SDLCレイヤー）はファイル（コードレイヤー）に関連します。ユーザー（SDLCレイヤー）は、含まれるファイルを最後に変更した場合、定義（コードレイヤー）のオーナーとなります。

パフォーマンス

GitLab Orbitは独立したKubernetesクラスターで動作し、GitLabインスタンスとコンピューティングやメモリを共有しません。

大規模なグループ（数千のプロジェクト、数百万行のコード）の初回インデックス作成は数分で完了します。変更後の増分再インデックス作成は、変更の規模に応じて数秒から数分で完了します。

クエリの実行

すべてのクエリは同じパスを経由します:

1. GitLab OrbitはJSONクエリペイロードを受信します（REST、MCP、またはGitLab Duo Agent Platform経由）。
2. クエリエンジンが現在のスキーマに対してクエリを検証します。
3. GitLab OrbitがJSON DSLをClickHouse SQLにコンパイルします。
4. ClickHouseがグラフテーブルに対してクエリを実行します。
5. GitLab Orbitが認可フィルタリングを適用します。結果は、リクエストしたユーザーがGitLabでアクセス権を持つエンティティにスコープされます。詳細については、セキュリティを参照してください。
6. GitLab Orbitが型付きJSONの結果を返します。

クエリレスポンスでコンパイル済みSQLを取得するには、options.include_debug_sql: trueを設定します。このフィールドは、インスタンス管理者およびレポーター以上のアクセス権を持つGitLab組織の直接メンバーにのみ表示されます。

データ保持と削除

グループでGitLab Orbitを無効にしても、インデックス作成済みのデータはすぐには削除されません。GitLab Orbitは30日間データを保持するため、グラフ履歴を失わずに再度有効化できます。猶予期間が終了すると、すべてのノード、エッジ、インデックス作成チェックポイントを含む、そのグループのすべてのグラフデータが完全に削除されます。

30日が経過する前にGitLab Orbitを再有効化した場合、削除はキャンセルされ、中断した箇所からインデックス作成が再開されます。