orbit

Orbit (GitLab Knowledge Graph) skill

Query the GitLab Knowledge Graph (product name Orbit) via the typed glab orbit remote CLI subcommands (shipped in glab v1.94.0+). The typed CLI handles the Content-Type header, response framing, and exit codes for you — always go through glab orbit remote.

Discovery

glab orbit remote --help and glab orbit remote query --help are the authoritative usage references. For entity properties, prefer the recipes in references/recipes.md over schema introspection — recipes already encode the columns and filters that are known to work.

If you do need to introspect, call schema at most once per session and pass entity names to scope the response:

glab orbit remote schema MergeRequest Project   # scoped properties
glab orbit remote dsl                           # full query DSL JSON Schema

Always fetch the DSL with glab orbit remote dsl — it is the source of truth for the query body shape.

Calling schema without arguments returns the full ontology (~28 KB) and is rarely what you want. Re-fetching schema between turns is pure latency — schemas do not change within a session. Cache the response (or just keep it in agent context) and reuse it.

Each glab orbit remote query invocation has fixed per-call overhead (process startup, auth load, HTTPS round-trip). Prefer one aggregation query over N traversal queries when the question is "how many X grouped by Y", and batch related lookups where possible.

Running a query

Write the request body to a file and pass it to glab orbit remote query. Default output is llm (compact, agent-friendly); pass --format raw to pipe into jq. Endpoints are user-scoped — do not pass -R owner/repo.

cat > /tmp/q.json <<'JSON'
{
  "query": {
    "query_type": "traversal",
    "nodes": [
      {"id": "p",  "entity": "Project",
       "filters": {"id": {"op": "eq", "value": 278964}}},
      {"id": "mr", "entity": "MergeRequest",
       "columns": ["iid", "title", "state"]}
    ],
    "relationships": [
      {"type": "IN_PROJECT", "from": "mr", "to": "p"}
    ],
    "order_by": {"node": "mr", "property": "created_at", "direction": "DESC"},
    "limit": 5
  }
}
JSON
glab orbit remote query /tmp/q.json