GitLab Orbit Specification

Nature & Status

GitLab Orbit is the canonical derived engineering context graph for the Bluefly estate. - Status: Beta / Analytical & Advisory (READY_FOR_PRODUCTION=NO). - Rule: ORBIT DISCOVERS RELATIONSHIPS. GITLAB PROVES CURRENT STATE. AGENTS EXECUTE THROUGH THE OWNER. - Operational Reality: Orbit is point-in-time and derived from indexing cycles. It assists discovery, blast radius analysis, and correlation, but does not substitute for live GitLab API transactional verification.

Estate Indexing & Reconciliation Notice

• Orbit Remote Observed Universe: 193 projects indexed in group blueflyio.
• GitLab Authoritative Estate State:
• Non-archived projects: 133
• Canonical active projects: 123
• Removal review: 7
• Pending deletion: 3
• Classification: ORBIT_INDEXED_PROJECTS=193, GITLAB_CANONICAL_ACTIVE=123. The difference represents subgroup forks, historical templates, or archived nodes indexed by Orbit's top-level crawler. Estate decisions MUST reference authoritative GitLab API queries.

Remote vs Local Architecture

========================================================================================
FEATURE             ORBIT REMOTE                       ORBIT LOCAL
========================================================================================
HOSTING / BACKEND   GitLab.com ClickHouse              Workspace ~/.orbit/graph.duckdb
INDEXED SCOPE       Top-level group `blueflyio`        Checked-out Git repository
                    (default branch source & SDLC)     (current working branch)
INDEXED DOMAINS     Definitions, Imports, Files,       Definitions, Imports, Classes,
                    Pipelines, Jobs, Deployments,      Functions, Local AST references
                    MRs, Diffs, Vulnerabilities
PRIMARY USE         Estate-wide blast radius, CI       Deep branch-level code analysis
                    failure clustering, MR collisions  before commit / push
INTERFACE           glab orbit remote / Orbit MCP      glab orbit local / Local MCP
========================================================================================

Transport & Access Mechanics

1. Remote MCP Interface:
2. URL: https://gitlab.com/api/v4/orbit/mcp
3. Command discovery layer: list_commands exposing invoke_command with payloads:
   • query_graph (JSON Graph DSL)
   • get_graph_schema
   • get_query_dsl
   • get_response_format
4. Antigravity / Client Constraint: Uses mcp-remote wrapper to handle OAuth discovery natively.
5. Local MCP Interface:
6. Server: glab orbit local mcp serve exposing index, get_graph_schema, run_sql.
7. Identity Boundary:
8. Orbit queries inherit the GitLab Service Account credentials of the calling agent (blucity_<role>), ensuring visibility matches exact permissions.

Relationship to other context sources

Orbit is DERIVED/ADVISORY — see README.md §3. It discovers relationships GitLab actually owns; GitLab proves current state, Orbit never overrides it.