CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

orbit

Use Orbit (`glab orbit` or `orbit`) to search code and read it with callers and tests. It reads MRs, issues, and failed jobs with the code they cite. Graph queries answer relationship and aggregation questions across GitLab. Skip it for writes that `glab` handles.

Quality

79%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/orbit/SKILL.md
SKILL.md
Quality
Evals
Security

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).
  • For packages, their files, dependencies and vulnerabilities, and container repositories, load the orbit-package-registry skill first: glab orbit skills get orbit-package-registry.

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.

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, 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

TopicLocation
First-run setup, exit codes, service health, iteration budgetreferences/troubleshooting.md
openCypher 9-based syntax and paste-ready queriesreferences/gql.md
Empty results and query validation errorsreferences/gql.md
Reporting results and coverage caveatsreferences/reporting.md
Maintaining this skill (contributing, doc sync)references/maintaining.md
Repository

gitlabhq/orbit-knowledge-graph

Path

skills/orbit/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.