Orbit

Orbit exposes GitLab.com’s experimental Knowledge Graph API through six read-only MCP tools — status, schema, tools, dsl, query, and graph_status. It is available only when the server connects to https://gitlab.com and the Enterprise/Premium catalog is enabled with Ultimate (GITLAB_TIER=ultimate, or --tier=ultimate in HTTP mode). The legacy GITLAB_ENTERPRISE=true/--enterprise flags still work but are deprecated. Orbit never writes: every tool inspects health, schema, or indexed data, or runs a read-only graph query.

When is Orbit available?

Orbit registers only on GitLab.com Ultimate connections. It requires the https://gitlab.com host and the Enterprise/Premium catalog enabled with Ultimate. In meta-tool mode it appears as the single gitlab_orbit tool with six actions; in individual mode it appears as six gitlab_orbit_* tools. Every Orbit tool is read-only.

Requirement	Value
GitLab host	`https://gitlab.com`
Catalog	Enterprise/Premium
Meta-tool mode	`gitlab_orbit` with six actions
Individual mode	Six `gitlab_orbit_*` tools
Write behavior	Read-only

Self-managed GitLab instances do not register Orbit tools, even when the Enterprise/Premium catalog is enabled.

Actions

Action	Individual tool	Purpose
`status`	`gitlab_orbit_status`	Check Orbit service health and component status
`schema`	`gitlab_orbit_schema`	Inspect the graph ontology and optionally expand node definitions
`tools`	`gitlab_orbit_tools`	Discover the live Orbit query manifest
`dsl`	`gitlab_orbit_dsl`	Retrieve the Orbit query DSL schema or LLM grammar
`query`	`gitlab_orbit_query`	Execute a read-only Knowledge Graph query object
`graph_status`	`gitlab_orbit_graph_status`	Inspect indexing status for a namespace, project, or full path

What is the typical flow?

The typical Orbit flow discovers the live schema first, then runs a typed query — never the other way around, because the ontology and DSL served by GitLab.com can change. Confirm the service is up with status, inspect the graph with schema, fetch the live query manifest with tools, optionally retrieve the DSL grammar with dsl, then submit a query object to query.

Call gitlab_orbit with action: "status" to confirm the service is available.
Call action: "schema" to inspect graph domains, nodes, and relationships.
Call action: "tools" before action: "query" to obtain the live query schema served by GitLab.com.
(Optional) Call action: "dsl" to retrieve the Orbit query DSL schema or LLM grammar.
Pass a JSON query object to action: "query" with response_format set to raw or llm.

Query DSL variants

The query parameter on the query action is a JSON object whose query_type selects one of four variants. The diagram below summarizes the smallest accepted shape for each variant. A Mermaid graph TD is the right tool because the four variants share a single query_type discriminator and only diverge on the sibling keys — a tree makes the discriminants and required fields legible at a glance.

Discover → query workflow

The recommended pattern is to discover the live schema first (schema, then optionally dsl), then execute a typed query through query. A sequenceDiagram is the right tool because the steps involve four distinct actors (AI client, MCP server, GitLab.com, the Orbit indexer) and the response boundaries matter — the LLM should not assume the schema returned by dsl is stable.

Example: Check Orbit status

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "status"
  }
}

Example: Get graph schema

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "schema",
    "params": {
      "expand": ["Project", "User"],
      "response_format": "llm"
    }
  }
}

Example: Get Orbit tool manifest

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "tools"
  }
}

Example: Get Orbit query DSL

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "dsl",
    "params": {
      "response_format": "llm"
    }
  }
}

Example: Run a Knowledge Graph query

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "query",
    "params": {
      "query": {
        "query_type": "traversal",
        "node": {
          "id": "p",
          "entity": "Project",
          "filters": {
            "full_path": { "op": "starts_with", "value": "gitlab-org/" }
          },
          "columns": ["id", "full_path"]
        }
      },
      "response_format": "llm"
    }
  }
}

Example: Check indexing status

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "graph_status",
    "params": {
      "project_id": 278964,
      "response_format": "llm"
    }
  }
}

Action details

`status` — Check Orbit service health

Returns cluster health and backend component status. Use to verify Orbit is available for your token and project.

Example: See above.

`schema` — Inspect the graph ontology

Returns the Orbit graph ontology, including schema version, domains, node summaries, and edges. Use expand to get detailed node definitions. Supports response_format (raw or llm).

Example: See above.

`tools` — Discover the Orbit tool manifest

Returns the live Orbit MCP tool manifest. Use before query to discover supported query shapes and parameter schemas.

Example: See above.

`dsl` — Retrieve the Orbit query DSL schema or LLM grammar

Returns the Orbit query DSL as a JSON Schema (raw) or LLM grammar (llm). Useful for advanced query construction and LLM integration.

Example: See above.

`query` — Execute a Knowledge Graph query

Runs a read-only Knowledge Graph query. The query parameter must match the schema from tools. Supports response_format (raw or llm).

Example: See above.

`graph_status` — Inspect indexing status

Returns graph indexing status for a namespace, project, or full path. Use to check if a project is indexed and ready for queries.

Example: See above.

How do I discover query schemas?

In meta-tool mode, action parameter schemas are available through MCP resources — read them to learn the exact params shape for each Orbit action without expanding every schema in tools/list. These resources remain available with CAPABILITY_SURFACE=full or minimal, regardless of META_PARAM_SCHEMA mode.

Resource	Purpose
`gitlab://tools/gitlab_orbit.status`	Parameters for service health checks
`gitlab://tools/gitlab_orbit.schema`	Parameters for ontology inspection
`gitlab://tools/gitlab_orbit.tools`	Parameters for query manifest discovery
`gitlab://tools/gitlab_orbit.dsl`	Parameters for DSL schema/grammar
`gitlab://tools/gitlab_orbit.query`	Parameters for Knowledge Graph queries
`gitlab://tools/gitlab_orbit.graph_status`	Parameters for indexing status checks

How do I run the live tests?

Orbit ships with a build-tag-gated live test suite at test/e2e/orbit/live_test.go that exercises each handler against the real https://gitlab.com/api/v4/orbit/* endpoints. The suite has four entry points and 41 subtests covering all six handlers, the canonical Query DSL shapes, fixture-based smoke tests, and the full DSL feature surface. The orchestrator make test-e2e-gitlab-com provisions kg-fixtures and security-fixtures projects in your namespace (idempotent), waits for the Orbit indexer to catch up, then runs the tests:

# Add a Personal Access Token (api scope) to .env first
echo 'GITLAB_COM_TOKEN=glpat-...' >> .env

# Default namespace is plens1; override with ORBIT_FIXTURES_NAMESPACE
make test-e2e-gitlab-com ORBIT_FIXTURES_NAMESPACE=acme-research

# When fixtures are already provisioned, run only the tests
GITLAB_COM_TOKEN=glpat-... \
  go test -tags orbitlive -count=1 -v -timeout 300s ./test/e2e/orbit/

See Orbit live test fixtures for the fixture layout, the scripts/setup-orbit-fixtures.sh reproducer, and the indexer caveat (transient error state is normal and the tests are informational, not strict equality).

Frequently asked questions

What are the four Orbit query_type variants?

The query action accepts a JSON query object whose query_type selects one of four variants: traversal (walk nodes by entity, node_ids, filters, or id_range), aggregation (group and aggregate over nodes), neighbors (expand a bounded node's neighbors), and path_finding (find paths between two or more bounded nodes, max_depth 1 to 3). All four share the single query_type discriminator and diverge only on their sibling keys.

Is Orbit available on self-managed GitLab?

No. Orbit is available only when GitLab MCP Server connects to https://gitlab.com. Self-managed GitLab instances do not register Orbit tools, even when the Enterprise/Premium catalog is enabled, because the underlying experimental Knowledge Graph API is hosted on GitLab.com. There is no flag that adds Orbit to a self-managed connection.

What license and configuration does Orbit require?

Orbit requires GitLab Ultimate on a GitLab.com connection. Enable it with GITLAB_TIER=ultimate in stdio mode or --tier=ultimate in HTTP mode. The legacy GITLAB_ENTERPRISE=true and --enterprise flags still work as a fallback but are deprecated. When these conditions are met, Orbit appears as the gitlab_orbit meta-tool (six actions) or six gitlab_orbit_* individual tools.

Is Orbit read-only?

Yes. All six Orbit tools are read-only. status, schema, tools, dsl, and graph_status only inspect health, ontology, manifest, DSL, and indexing state, and query runs read-only Knowledge Graph query objects against the index. No Orbit action mutates GitLab data, so Orbit is safe to expose even in cautious deployments.

How do I learn the exact parameters for an Orbit action?

In meta-tool mode, read the per-action MCP resource — for example gitlab://tools/gitlab_orbit.query returns the parameter schema for the query action. These resources stay available with CAPABILITY_SURFACE=full or minimal and in any META_PARAM_SCHEMA mode. You can also call action: "tools" to fetch the live query manifest served by GitLab.com before constructing a query.

Maintained by José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar All projects

Orbit

When is Orbit available?

Actions

What is the typical flow?

Query DSL variants

Discover → query workflow

Example: Check Orbit status

Example: Get graph schema

Example: Get Orbit tool manifest

Example: Get Orbit query DSL

Example: Run a Knowledge Graph query

Example: Check indexing status

Action details

status — Check Orbit service health

schema — Inspect the graph ontology

tools — Discover the Orbit tool manifest

dsl — Retrieve the Orbit query DSL schema or LLM grammar

query — Execute a Knowledge Graph query

graph_status — Inspect indexing status

How do I discover query schemas?

How do I run the live tests?

Frequently asked questions

What are the four Orbit query_type variants?

Is Orbit available on self-managed GitLab?

What license and configuration does Orbit require?

Is Orbit read-only?

How do I learn the exact parameters for an Orbit action?

`status` — Check Orbit service health

`schema` — Inspect the graph ontology

`tools` — Discover the Orbit tool manifest

`dsl` — Retrieve the Orbit query DSL schema or LLM grammar

`query` — Execute a Knowledge Graph query

`graph_status` — Inspect indexing status