| name | orbit |
| description | Query GitLab Orbit via `glab orbit remote` CLI subcommands or run a local copy with `glab orbit local`. Use for code-structure questions (who calls this function, where is this symbol defined), cross-project dependency and blast-radius analysis, merge-request and contributor queries that require relationship traversal or aggregation, repository map / repo-map generation, and any question spanning relationships, cross-entity joins, or multi-entity aggregation across GitLab entities (projects, users, MRs, issues, pipelines, files, definitions, vulnerabilities). Do not use for single-entity GitLab lookups or write operations that `glab` handles directly (e.g. `glab mr view`, `glab mr create`). |
| version | 0.26.0 |
| license | MIT |
| metadata | {"audience":"developers","keywords":"orbit, knowledge-graph, gkg, graph, query, glab","workflow":"ai"} |
Orbit skill
Query GitLab Orbit (previously GitLab Knowledge Graph) 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.
Prerequisites
If glab orbit commands fail (command not found, auth errors, feature-flag
exit codes), work through the first-run setup checklist in
references/prerequisites.md.
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 —
they already encode the columns and filters known to work.
If you must introspect, call glab orbit remote schema <Entity…> with explicit
entity names — always pass the entity names you need rather than the unscoped
form, which returns ~17 KB+ of output. Call schema at most once per session;
schemas don't change mid-session. Use glab orbit remote dsl for the full DSL
JSON Schema. Note that per-node outgoing_edges/incoming_edges are arrays
of strings (edge type names), not objects — use --jq accordingly (e.g.
schema Project --jq '.nodes[] | select(.name=="Project") | .properties').
Each glab orbit remote 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 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.
Many filters need a numeric project ID. For the repository you are in, let
glab resolve it from the Git remote rather than querying for it:
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":
glab orbit remote query /tmp/q.json
filters is an object keyed by property name — not an array. Use either
shorthand equality ({"state": "opened"}) or the operator form
({"iid": {"eq": 1216}}). Operators: eq, gt, lt, gte,
lte, in, contains, starts_with, ends_with, is_null, is_not_null,
plus text-token operators (token_match, all_tokens, any_tokens) for
text-indexed properties — see query_language.md.
All queries declare node selectors in the nodes array — a 1-element array
for neighbors and single-node traversal; multi-node traversal,
aggregation, and path_finding add relationships.
- For multi-hop traversal edges, set
relationships[].hops to an
inclusive [min, max] pair ("hops": [1, 3]; [2, 2] for exactly 2).
Omitted means [1, 1]. Max 3.
- For path_finding queries, set
path.max_depth inside the required
path sub-object. Max 3. hops does not apply to path_finding.
When endpoints use filters, include path.rel_types to bound fan-out;
path_finding follows edges only in their schema direction (see
recipe pitfall).
Common pitfalls
Read references/recipes.md before constructing a
query — the same question often has one canonical paste-ready shape and several
wrong-looking-correct ones. Four traps recur:
- "Pipelines for a merge request" requires
Pipeline.source = "merge_request_event". Both Pipeline.merge_request_id and the
MergeRequest --TRIGGERED--> Pipeline edge return parent and downstream
child pipelines (source = "parent_pipeline"). Apply the
source = "merge_request_event" filter (or the
canonical recipe)
to match the MR Pipelines tab.
- Prefer single-node queries when you can bound the target entity directly.
Adding nodes/relationships only to "anchor" a query (joining
Project +
MergeRequest + Pipeline when you already know merge_request_id) can
change the row shape and skew aggregation counts. If recipes.md shows a
single-node form, use it.
HAS_LATEST_DIFF vs HAS_DIFF for file history. HAS_LATEST_DIFF
points only at the most recent diff snapshot of an MR. "Every MR that ever
touched this file" needs HAS_DIFF (all snapshots) — HAS_LATEST_DIFF here
can substantially undercount long-lived files. See
recipe.- GitLab issues, epics, tasks, and incidents are the
WorkItem entity, not
Issue. Modern GitLab unifies these under work items, and Orbit follows the
same model: there is no Issue node, so entity: "Issue" is rejected. Query
WorkItem for any of them (see
recipe).
Iteration budget
A single user question should resolve in at most 5 query attempts. Tweaking
only limit/columns is not progress; changing entity, relationship type, or
a filter is. Validation errors (HTTP 400) count toward the budget. If you
exceed 5 without converging, give up loudly: report the shapes you tried,
what failed, and the next step — do not keep iterating or inflate a partial
answer. Full rules:
references/troubleshooting.md.
Reporting results
Orbit answers are graph queries against ClickHouse, not an authoritative source
of truth. Always surface known coverage gaps inline (e.g. HAS_LATEST_DIFF
vs HAS_DIFF, time-bounded aggregates) and show the query body so the user
can audit it. Do not add a "Methodology" header that implies rigor the data
lacks. Full guidance and worked examples:
references/reporting.md.
Repository map helpers
For code-structure orientation before planning a change, use a repo-map helper:
the native local command glab orbit local repo-map for an
uncommitted/branch-local checkout, or the bundled remote helper script (path
relative to this skill root, not the user's current repo) for a project already
indexed in Orbit Remote. See the repository-map rows in
References below.
Local CLI (glab orbit local)
glab orbit local downloads and runs a managed Orbit CLI binary for indexing
and querying a local copy of the graph (macOS/Linux only,
x86_64/aarch64). Prefer it over glab orbit remote when indexing a local
repository for offline analysis; use remote to query production. Install/run
with glab orbit local (add --install or --update). Full config keys and
pass-through args: references/local_cli.md.
References
