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.

Fix inaccurate guidance

If guidance is wrong or outdated (command, flag, or behavior), tell the user. With their confirmation, open a focused MR against metadata.source-project fixing metadata.source-path (one fix per MR, Conventional Commits). If they decline, note the discrepancy in one line and continue with the corrected command.

Discovery

glab orbit help and glab orbit <command> --help are the authoritative usage references. Run glab orbit skills to list available skills. Run glab orbit skills get orbit to print the composed skill (SKILL.md by default), or append a path such as references/local/cli.md to print a file. 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 schema <Entity...> with explicit entity names. The unscoped form returns about 40 KB of output. Call it at most once per session, because the schema does not change mid-session. In JSON mode, the DSL is documented in references/query_language.md. In GQL mode, run CALL db.schema() instead. The schema command returns an object with nodes and edges arrays and does not accept --jq, so pipe into jq. Only named nodes have properties. Edges list endpoints with a source and a target:

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

The default-off Rails orbit_gql_queries flag selects one mode per user: JSON objects when off, GQL strings when on. Follow only the active mode's discovery; a mismatched query rejects without parser fallback. GQL mode hides and rejects get_query_dsl; use CALL db.schema() instead. The JSON recipes below apply only when the flag is off.

The named-query catalog at GET /api/v4/orbit/query/templates is rendered in that mode. Do not reuse discovery results across users or mode changes. Entries contain only name, description, and raw_query; there is no client language selector. See catalog troubleshooting.

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

Queries accept at most 16 predicates total. Each node or relationship filter operator counts once, including repeated entries. A nonempty node_ids list counts as one predicate; id_range counts as two. An IN list counts once, with its existing value limit. If rejected, remove redundant conditions or simplify the query.

Write the request body to a file and pass it to glab orbit query --file. 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 --file /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 helper

For code-structure orientation on a project already indexed by GitLab Orbit, use the bundled remote helper script. The script path is relative to this skill root, not the user's repository. See the repository-map row in References.

Managed CLI

glab orbit downloads, verifies, and runs the GitLab Orbit CLI binary from the orbit-cli package (macOS, Linux, and Windows). grep and context read the local graph and index the working tree on their own. workspace groups the other local-graph commands (index, list, mcp serve). query, status, and schema call the GitLab Orbit API.

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. Put these flags before the subcommand (glab orbit --yes status); the binary rejects --yes after other subcommands, except for setup and uninstall, which take their own. glab's own update command also takes --yes. glab help orbit 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_cli_auto_run true and glab config set orbit_cli_auto_download true. Point glab at your own build with glab config set orbit_cli_binary_path /path/to/orbit or the GLAB_ORBIT_CLI_BINARY_PATH env var. That skips download, version checks, and updates. glab records orbit_cli_binary_version, orbit_cli_binary_checksum, and orbit_cli_last_update_check itself. Do not set them by hand.

References