GitLab Orbit

Software lifecycle context graph for AI agents

Docs · Quickstart · Orbit Local · Orbit Remote · AI coding agents

Index your GitLab SDLC and source code as one property graph, then query it from the GitLab UI, a CLI, MCP, or REST. Orbit ships in two shapes: Orbit Local, a single-binary CLI that builds a code-only graph from any repository on your machine, and Orbit Remote, the hosted graph that spans a top-level GitLab.com group.

Beta. The Query DSL and ontology may change. Orbit Remote 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
• Orbit Local 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.

Two ways to run Orbit

Orbit Local

Orbit Local runs on your machine. 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. The install step downloads a release artifact over HTTPS.

What it indexes: directories, files, function and class definitions, and cross-file import references. It indexes the same 11+ languages as Orbit Remote. Multiple checkouts share one database at ~/.orbit/graph.duckdb, each identified by its filesystem path. Reindexing after switching branches replaces that checkout's previous graph; use separate worktrees to retain multiple branches.

Access method	Use for
orbit CLI	Index, query, and inspect the local graph
glab orbit local	Install and run Orbit Local through glab
MCP	Expose the local graph to AI coding agents over stdio

Start with Orbit Local getting started.

Orbit Remote

Enable Orbit on a top-level GitLab.com group. Orbit indexes your SDLC and source code into a managed property graph.

What it indexes: SDLC objects (including groups, projects, users, notes, merge requests, pipelines, jobs, work items, milestones, labels, vulnerabilities, findings) and source code on the default branch across 11+ languages including Ruby, Java, Kotlin, Python, TypeScript, JavaScript, Rust, Go, C#, C, C++, PHP, Bash/Shell, and Elixir.

Access method	Use for
GitLab Duo Agent Platform	Natural-language questions in the GitLab UI
MCP	Claude Code, Codex, Cursor, opencode, Gemini CLI
glab orbit remote	Typed CLI subcommands for scripts and discovery
REST API	Pipelines, custom tooling, scripts

Start with Orbit Remote getting started.

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

Quickstart: Orbit Local

# 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'

Quickstart: Orbit Remote

# Requires glab 1.94+, 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 remote schema

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 remote query /tmp/orbit-query.json

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

Features

Capability	Orbit Local	Orbit Remote
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

Orbit Local exposes raw SQL, so traversals are expressed as joins. Orbit Remote supports aggregations, traversals, neighbors, and pathfinding at multi-billion-edge scale.

Architecture

Orbit shares a Rust workspace and YAML ontology across two runtimes. Orbit Remote runs the gkg-server service modes against ClickHouse and serves HTTP, gRPC, REST, and MCP requests. Orbit Local runs the standalone orbit CLI 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 config still use the engineering name GKG (binary gkg-server, config prefixes GKG_*, metrics).

• 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.