GitLab Orbit

Software lifecycle context graph for AI agents

Docs · Quickstart · Getting started · AI coding agents

Orbit indexes your GitLab SDLC and source code into one property graph, then lets you query it from the GitLab UI, a CLI, MCP, or REST. The graph can live on your machine — a single binary that builds a code-only graph from any repository, offline — or in the hosted service that spans a top-level GitLab.com group across SDLC and code. Same ontology, same query surface.

Beta. The Query DSL and ontology may change. The hosted graph is gated by the knowledge_graph feature flag and must be enabled on a top-level group.

For contributors

New here? Start with:

• CONTRIBUTING.md — build setup, test commands, MR conventions
• Quickstart — index a repo and run queries in minutes, no server needed
• User docs — understand what Orbit does before changing it
• orbit::hackathon issues — curated issues for new contributors

Most contributions don't require Rust experience: ontology YAML, docs, cookbook recipes, and language parser stubs are all approachable without deep Rust knowledge.

Using Orbit

The orbit CLI parses a local repository, extracts definitions and cross-file references, and writes a code-only call graph to a single DuckDB file — no GitLab account is required at query time, and it runs offline after install. The hosted graph additionally indexes your SDLC (groups, projects, users, notes, merge requests, pipelines, jobs, work items, milestones, labels, vulnerabilities, findings) and default-branch source code across a top-level GitLab.com group, enforcing GitLab authorization on every query.

Both cover the same 11+ languages: Ruby, Java, Kotlin, Python, TypeScript, JavaScript, Rust, Go, C#, C, C++, PHP, Bash/Shell, and Elixir. Local checkouts share one database at ~/.gitlab/orbit/graph.duckdb, each identified by its filesystem path; reindexing after switching branches replaces that checkout's graph, so use separate worktrees to keep multiple branches.

Access method	Use for
orbit CLI	Index, query, and inspect a graph directly
glab orbit	Install and run Orbit through glab
MCP	Expose the graph to AI coding agents over stdio
GitLab Duo Agent Platform	Natural-language questions in the GitLab UI
REST API	Pipelines, custom tooling, scripts

Start with the getting started guide.

flowchart LR
    subgraph GitLab["GitLab instance"]
        SDLC[SDLC data]
        Code[Source code]
    end

    SDLC -- CDC --> DIP[Data Insights Platform]
    DIP --> CH[(ClickHouse)]
    Code -- Rails API --> Orbit[Orbit service]
    CH <--> Orbit

    Orbit --> REST[REST API]
    Orbit --> MCP[MCP tools]
    Orbit --> DAP[GitLab Duo Agent Platform]

Loading

Quickstart

Index a local repository

# Install (macOS, Linux glibc, Linux musl; --libc musl forces the static build)
curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash

# Index the current repository, then query it
orbit index .
orbit sql 'SELECT count(*) FROM gl_definition'

Query the hosted graph

# Requires glab 1.117+, authenticated (glab auth login), with Orbit enabled on your group.
# See docs/source/remote/getting-started.md. Replace your-group/ with your top-level group path.
glab orbit ontology

Put the request body in /tmp/orbit-query.json:

{
  "query": {
    "query_type": "traversal",
    "nodes": [{
      "id": "p",
      "entity": "Project",
      "filters": {
        "full_path": {"starts_with": "your-group/"}
      }
    }],
    "limit": 5
  }
}

glab orbit query /tmp/orbit-query.json

The cookbook has blast-radius, dependency, pipeline-health, and vulnerability recipes.

Features

Capability	Local graph	Hosted graph
Scope	Code only	SDLC and code
Query interface	Raw DuckDB SQL	Query DSL compiled to ClickHouse SQL
GitLab authorization	Filesystem permissions only	Enforced per query
Runs offline	Yes (after install)	No

The local graph exposes raw SQL, so traversals are expressed as joins. The hosted graph adds the Query DSL — aggregations, traversals, neighbors, and pathfinding at multi-billion-edge scale.

Architecture

Orbit shares a Rust workspace and YAML ontology across two runtimes. The hosted service runs the gkg-server service modes against ClickHouse and serves HTTP, gRPC, REST, and MCP requests. The orbit CLI runs standalone against DuckDB and exposes direct commands plus a stdio MCP server. See the design documents and the data model for the full picture.

Documentation

User docs	Developer docs
Orbit overview	Local development
AI coding agents	Domain glossary (CONTEXT.md)
Remote: how it works · indexing · schema · cookbook · Query DSL	Design documents
Local: how it works · indexing · schema · orbit CLI	Adding a language
MCP tool reference	E2E testing
Configuration	Indexer crate guide
Troubleshooting	Runbooks

The published site is docs.gitlab.com/orbit.

Development

Build, test, and run from source

All tasks run through mise.

mise build            # Build the workspace
mise test:fast        # Unit + fast integration tests
mise test:integration # Full integration suite (requires Docker)
mise lint:code        # Clippy with warnings as errors
mise lint:code:fix    # Apply clippy fixes
mise server:start     # Run gkg-server locally

The product name is Orbit. The binary and metrics still use the engineering name GKG (binary gkg-server, metric names).

• Local development guide
• E2E testing harness
• Adding a new language
• Indexer crate guide
• Operational runbooks
• Server configuration runbook
• Contributing — quickstart, testing, linting, and MR conventions.

Project and operations

Epics, related repositories, infrastructure, contacts, and SOX boundary

Epic landscape

• Primary GA epic (#19744)
• L4: Introduce GitLab Orbit (#773)
• GKG on Dedicated (#915, confidential)
• First Iteration, predecessor (#17514, closed)
• Workstream epics: Product (#20884) · Core Development (#20357) · Security (#20248) · Infra/Delivery (#36) · Architecture & Discovery (#20885)
• Cross-functional: Infra support (#1804) · DataSec support (#407) · DE&M data product (#86) · Monetization (#79)
• PREP readiness review !64
• Issues labeled knowledge graph (the historical feature label)

Related repositories

Repository	Role
orbit/knowledge-graph	This repo. Server, indexer, CLI.
orbit/orbit-helm-charts	Official Helm chart.
orbit/orbit-e2e-harness	GKE bootstrap for end-to-end tests.
orbit/documentation/orbit-artifacts	Offsite transcripts and session notes.
analytics-section/siphon	External CDC pipeline that feeds the datalake.
analytics-section/platform-insights/siphon-helm-charts	Production Siphon Helm chart.
gitlab-org/gitlab	Rails monolith. Owns authorization and serves source code over the internal API.
gitlab-org/rust/build-images	CI builder images.

Infrastructure

• Helmfiles: Siphon · NATS · Data Insights Platform
• ClickHouse Cloud Terraform: gstg and gprd clickhouse-cloud.tf files under config-mgmt (environments/gstg/ and environments/gprd/)
• Architecture readiness
• Data Insights Platform infra module

Pipeline operations

• SDLC indexing runbook
• Code indexing runbook
• Server configuration runbook
• All runbooks

Billing and SOX

Billing emission is on the SOX audit boundary. Before touching billing code, read SOX billing boundary.

• crates/orbit-billing/: Snowplow billing-event emission and CDot quota enforcement.
• crates/orbit-server/src/billing_adapter.rs: the single Claims to BillingInputs conversion point.

People

Role	DRI
Engineering lead	@michaelangeloio
Product Manager	@mcorren
TPM	@lyle
Siphon and DIP architecture	@ahegyi

Cross-functional partners

Name	Area
Nitin Singhal (@nitinsinghal74)	ELT lead
Stephanie Jackson	Infrastructure, SRE, PREP
Ankit Bhatnagar (@ankitbhatnagar)	NATS, DIP
Gus Gray (@ggray-gitlab)	Security, AuthZ design
Jason Plum (@WarheadsSE)	Delivery, Self-Managed, Dedicated
Brian Greene (@bgreene1)	Ontology standards
Dennis Tang (@dennis)	Analytics stage, ClickHouse operations
Nick Leonard (@nickleonard)	Design
Jerome Ng (@jeromezng)	Usage billing system architect

GitLab stage: Orbit. Group: Context Systems.

Maintainers and contributors

Orbit was founded by:

• @michaelangeloio (Angelo Rivera). Overall engineering lead.
• @michaelusa (Michael Usachenko). Code graph and query engine.
• @jgdoyon1 (Jean-Gabriel Doyon). ETL engine and the overall indexing engine.
• @bohdanpk (Bohdan Parkhomchuk). Infrastructure, web server, and security.

Orbit has received contributions from 75+ GitLab team members. See the contributors graph for the live list.

License

GitLab Enterprise Edition (EE) License. See LICENSE.md.