orbit

Orbit skill

Query GitLab Orbit (previously GitLab Knowledge Graph) through the flat glab orbit command tree. It needs glab v1.126.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.

Query language

Queries use read-only openCypher 9-based syntax (MATCH ... RETURN). If you find a legacy JSON query, run glab orbit skills get orbit-gql-migration to convert it.

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.

Run CALL db.schema() once per session, because the schema does not change mid-session. It lists every relationship as (Source)-[:TYPE]->(Target) and the properties of the common nodes, such as User, Project, Group, MergeRequest, and WorkItem. Run CALL db.schema('Node') only for a node it does not list properties for. Query syntax and paste-ready queries are in references/gql.md.

Batch schema reads: make every schema read a question needs in one shell command, not one command per read. Each CALL db.schema call takes one node. On the first read, chain the overview with the nodes that the question names. Later, batch only the new node reads.

glab orbit query 'CALL db.schema()'; echo; glab orbit query "CALL db.schema('Vulnerability')"; echo; glab orbit query "CALL db.schema('Pipeline')"

The named-query catalog at GET /api/v4/orbit/query/templates is rendered in your 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 aggregate query, with count(...) in RETURN, over N lookups for "how many X grouped by Y", and batch related lookups.

When editing Orbit docs or skills, fence executable GQL queries as gql orbit-query so docs smoke tests run them.

Running a query

Pass query text inline. The CLI builds the request envelope, so a short query needs no temporary file:

glab orbit query 'CALL db.schema()'
glab orbit query "CALL db.schema('Project')"
glab orbit query "MATCH (p:Project {full_path: 'gitlab-org/gitlab'}) RETURN p.id, p.full_path LIMIT 1"

With a standalone install, use orbit query instead of glab orbit query. Quote the whole query for the shell; single-quoted string literals then need double quotes around the query.

--file reads a JSON request envelope whose query field holds the query text, not a bare query file. --file - reads that envelope from stdin. 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.

Common pitfalls

Read references/gql.md before you construct a query. These traps recur:

• At least one node needs an ID or a property filter. LIMIT does not bound the scan, so MATCH (p:Project) RETURN p LIMIT 5 rejects.
• Write relationship types after a colon: -[:AUTHORED]->. -[AUTHORED]-> declares a variable and rejects.
• Pipelines for a merge request need the source: 'merge_request_event' filter.
• Prefer a single anchored node when you can bound the target directly. Extra anchor nodes can change the row shape and skew aggregate counts.
• To find MRs that ever touched a file, use HAS_DIFF; see file history. Use HAS_LATEST_DIFF for one MR's current revision.
• Issues, epics, tasks, and incidents are the WorkItem node. There is no Issue node.
• There is no OR, XOR, RETURN DISTINCT, count(*), OPTIONAL MATCH, or WITH. DISTINCT works only inside count(): count(DISTINCT pl).

Iteration budget

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

Reporting results

Orbit answers come from graph queries, not an authoritative source. Flag known coverage gaps inline when they affect the result. Full guidance: references/reporting.md.

Choose the command

• orbit grep 'a|b' searches code, tests, config, and docs and labels each match with its enclosing definition. A plain query also searches the GitLab group behind origin over the network. For code only, pass the repository top-level as the path ($(git rev-parse --show-toplevel)). . scopes the search to the current directory, and widens when nothing matches there. Exit 1 means no match.
• orbit context <name> <path>:<lines> mr:42 job:9 reads several targets in one call. Definitions come with their callers and tests, and GitLab merge requests, issues, branches, pipelines, and jobs come with the local code they point at. A bare orbit context reads the current branch's merge request and CI failures.
• orbit query answers relationship and aggregation questions across GitLab entities through the GitLab Orbit API. Examples: who reviewed which merge requests, or which changes to an area failed CI. Write the query in the language below.

orbit grep 'retry_backoff|RetryBackoff'
orbit context src/retry.rs:40-90 retry_backoff mr:42

Run grep first, then context on the symbol you will change to get its callers, callees, and covering tests.

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, reset). The top-level index and list still run as deprecated aliases. 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

Topic	Location
First-run setup, exit codes, service health, iteration budget	references/troubleshooting.md
openCypher 9-based syntax and paste-ready queries	references/gql.md
Empty results and query validation errors	references/gql.md
Reporting results and coverage caveats	references/reporting.md
Maintaining this skill (contributing, doc sync)	references/maintaining.md