Orbit

Orbit skill

Query GitLab Orbit (previously GitLab Knowledge Graph) through the flat glab orbit command tree. It needs glab v1.117.0 or later. Hosted commands handle authentication, response framing, and exit codes. Local commands use the managed binary and the local DuckDB graph.

Prerequisites

If a glab orbit command fails with "command not found", an auth error, or a feature-flag exit code, work through the first-run setup.

Discovery

glab orbit help and glab orbit <command> --help are the authoritative usage references. For entity properties, prefer the recipes in references/recipes.md over schema introspection. They already encode the columns and filters known to work.

If you must introspect, call glab orbit ontology <Entity...> with explicit entity names. The unscoped form returns about 17 KB of output. Call it at most once per session, because the ontology does not change mid-session. glab orbit dsl prints the full DSL JSON Schema. The ontology command returns an object with a nodes array and does not accept --jq, so pipe into jq. Per-node outgoing_edges and incoming_edges are arrays of edge type names, not objects:

glab orbit ontology Project |
  jq '.nodes[] | select(.name == "Project") | .properties'

Each glab orbit query has fixed per-call overhead. Prefer one aggregation query over N traversal queries for "how many X grouped by Y", and batch related lookups.

When editing Orbit docs or skills, fence executable query JSON as json orbit-query so docs smoke tests run it.

Running a query

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

Many filters need a numeric project ID. For the repository you are in, let glab resolve it from the Git remote.

PROJECT_ID=$(glab api projects/:fullpath | jq -r '.id')

Put the request body in /tmp/q.json.

{
  "query": {
    "query_type": "traversal",
    "nodes": [
      {"id": "p",  "entity": "Project",
       "filters": {"id": {"eq": 278964}}},
      {"id": "mr", "entity": "MergeRequest",
       "columns": ["iid", "title", "state"]}
    ],
    "relationships": [
      {"type": "IN_PROJECT", "from": "mr", "to": "p"}
    ],
    "order_by": "-mr.created_at",
    "limit": 5
  }
}

glab orbit query /tmp/q.json

filters is an object keyed by property name, not an array. Every query declares its node selectors in the nodes array. Filter operators, multi-hop hops, and path_finding limits are in references/query_language.md. Paste-ready shapes for each query_type are in references/recipes.md.

Common pitfalls

Read the recipes before you construct a query. The same question often has one canonical shape and several wrong shapes that look correct. Four traps recur:

• Pipelines for a merge request need the source = "merge_request_event" filter. See the recipe.
• Prefer a single-node query when you can bound the target entity directly. Extra anchor nodes can change the row shape and skew aggregation counts.
• File history needs HAS_DIFF, not HAS_LATEST_DIFF. See the recipe.
• Issues, epics, tasks, and incidents are the WorkItem entity. There is no Issue node. See the recipe.

Iteration budget

Resolve a user question in at most 5 query attempts, validation errors included. Changing only limit or columns is not progress. Full rules: references/troubleshooting.md.

Reporting results

Orbit answers come from graph queries, not an authoritative source. Show the query body and its coverage gaps with every result. Full guidance: references/reporting.md.

Repository map helpers

For code-structure orientation before you plan a change, use glab orbit repo-map on a local checkout. For a project already indexed in Orbit Remote, use the bundled remote helper script. The script path is relative to this skill root, not the user's repository. See the repository-map rows in References.

Managed CLI

glab orbit downloads, verifies, and runs the Orbit binary from the orbit-local package (macOS, Linux, and Windows). The command selects the backend. index, grep, context, sql, schema, list, mcp, and repo-map use the local graph. query, status, ontology, dsl, tools, and graph-status use Orbit Remote.

glab handles --install, --update, and --yes itself and forwards everything else to the binary. --install and --update are mutually exclusive. --yes skips the confirmation prompts, so pass it in scripts and agent runs. glab orbit --help shows the wrapper help. glab orbit help and glab orbit <command> --help show the binary's.

glab orbit --install --yes   # install without running
glab orbit --update          # install the latest compatible version

Skip the confirmation prompts for good with glab config set orbit_local_auto_run true and glab config set orbit_local_auto_download true. Point glab at your own build with glab config set orbit_local_binary_path /path/to/orbit or the GLAB_ORBIT_LOCAL_BINARY_PATH env var. That skips download, version checks, and updates. glab records orbit_local_binary_version, orbit_local_binary_checksum, and orbit_local_last_update_check itself. Do not set them by hand.

References