GitLab Orbit architecture

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab Orbit is a read-only property graph of your GitLab data and code. GitLab builds it for each top-level group where GitLab Orbit is turned on, keeps it current, and checks your permissions on every query.

flowchart LR
  accTitle: How GitLab Orbit builds and serves the graph
  accDescr: The indexer reads GitLab data and the code on the default branch of each project, and writes the graph to the graph database. GitLab authorizes each query and serves the graph to the CLI, the MCP endpoint, the REST API, and GitLab Duo Agent Platform.
  data[GitLab data] --> indexer[Indexer]
  code[Code on the default branch] --> indexer
  indexer --> store[(Graph)]
  store --> gitlab[GitLab<br/>authorizes each query]
  gitlab --> cli[CLI]
  gitlab --> mcp[MCP endpoint]
  gitlab --> api[REST API]
  gitlab --> duo[GitLab Duo Agent Platform]

Graph layers

Each entity, such as a project, a user, or a function, is a node. Each relationship, such as AUTHORED from a user to a merge request, is a directed edge. The graph has two connected layers:

  • The software development lifecycle (SDLC) layer holds GitLab objects, such as groups, projects, merge requests, pipelines, and work items.
  • The code layer holds files, directories, definitions, and imports. A project contains branches, and a branch contains the files of the code layer.

For the full list of node types and relationships, see indexed data.

Indexing

After you turn on GitLab Orbit for a group, the indexer builds the graph from two sources:

  • SDLC data. GitLab streams changes through a change data capture (CDC) pipeline to the GitLab Data Insights Platform, and the indexer reads them from there. A new merge request, work item, or pipeline is in the graph in minutes.
  • Source code. The indexer fetches the files of the default branch through the GitLab internal API and Gitaly, parses them, and indexes again when the default branch changes. You cannot select another branch. An answer about code on another branch reflects the default branch. For code you have not merged, use the local graph.

Results show your data as of the last index cycle. The first index usually completes in a few minutes, and can take up to a few hours for large codebases. Later updates take seconds to minutes. To check the progress, see check indexing progress with the GitLab Orbit CLI.

Query execution

Queries use GQL, the GitLab Orbit query language. Every query follows the same path:

  1. GitLab receives the query from the CLI, the REST API, the Model Context Protocol (MCP) endpoint, or GitLab Duo Agent Platform.
  2. The query engine validates the query against the schema and compiles it to SQL.
  3. The graph database runs the SQL.
  4. GitLab removes each result you cannot access. For more information, see Security.

Hosting

On GitLab.com, a separate graph database stores the graph, and the GitLab Orbit services run in a separate Kubernetes cluster. They do not share compute or memory with GitLab.com. On GitLab Dedicated, GitLab runs GitLab Orbit for your instance. On GitLab Self-Managed, you run GitLab Orbit yourself. For more information, see GitLab Orbit on GitLab Self-Managed.

Data retention and deletion

When you turn off GitLab Orbit for a group, GitLab keeps the indexed data for 30 days. If you turn GitLab Orbit on again in that time, indexing continues from where it stopped. After 30 days, GitLab deletes all graph data of the group.