| stage | Analytics |
|---|---|
| group | Knowledge Graph |
| info | To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments |
| description | Enable GitLab Orbit Remote on GitLab.com and run your first query. |
| title | Get started with GitLab Orbit Remote |
{{< details >}}
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
{{< /details >}}
{{< history >}}
- Introduced in GitLab 18.10 with a feature flag named
knowledge_graph. Disabled by default. This feature is an experiment. - Changed to beta in GitLab 19.1.
{{< /history >}}
[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
- To turn on GitLab Orbit, the Owner role on the top-level group.
- To query a group after it has been indexed, the Reporter role or higher.
- To view security data, the Security Manager role. For more information, see roles required to query GitLab Orbit.
GitLab Orbit indexes top-level groups only. Subgroups and projects inherit indexing automatically.
- On the left sidebar, expand Your Work.
- Select Orbit > Configuration.
- Find your top-level group in the Indexes list.
- Toggle Enable.
GitLab Orbit begins indexing immediately. Initial indexing takes a few minutes for small groups and up to 30 minutes for groups with thousands of projects.
Check indexing status at any time:
glab orbit remote statusGitLab Orbit Remote exposes the same graph through three surfaces. Pick the one that matches who's querying:
| Method | Best for | Setup | Billing |
|---|---|---|---|
| GitLab Duo Agent Platform | End users in the GitLab UI | None | Zero-rated |
| MCP | Claude Code, Codex, other AI agents | One-time agent config | GitLab Credits |
| REST API | Scripts, dashboards, custom tooling | API token | GitLab Credits |
GitLab Orbit is wired into GitLab Duo Agent Platform. The GitLab Duo Agent, Planner Agent, Security Analyst Agent, Data Analyst Agent, CI Expert Agent, and Developer Flow call GitLab Orbit's list_commands and invoke_command tools automatically, running commands such as query_graph and get_graph_schema, when a question is best answered by graph traversal. No tool selection or configuration required.
For example, file a work item asking to rename the deploy_user method. The Developer Flow uses GitLab Orbit to identify every service that calls it, then drafts an MR that updates each one.
GitLab Duo queries are zero-rated and do not consume GitLab Credits.
See Use GitLab Orbit via MCP for setup. Once configured, you have two tools: query_graph and get_graph_schema.
The GitLab Orbit skill gives your AI agent query recipes, DSL guidance, and troubleshooting so it writes correct GitLab Orbit queries on the first attempt:
glab skills install --global orbitSee Set up AI coding agents with the GitLab Orbit skill for project-scoped install, update instructions, and what the skill contains.
Replace your-group with the top-level group path you enabled GitLab Orbit on. The full_path filter scopes the query so it passes GitLab Orbit's selectivity validation.
Put the request body in request.json:
{
"query": {
"query_type": "traversal",
"nodes": [{
"id": "p",
"entity": "Project",
"columns": ["name", "full_path"],
"filters": {
"full_path": {"starts_with": "your-group/"}
}
}],
"limit": 10
},
"format": "raw"
}curl --request POST \
--header "Authorization: Bearer <your_token>" \
--header "Content-Type: application/json" \
--data @request.json \
"https://gitlab.com/api/v4/orbit/query"- What GitLab Orbit indexes - understand coverage before writing queries
- Schema reference - explore the 28 node types and their properties
- Cookbook - copy-paste queries for common use cases
- Get started with GitLab Orbit Local - query a local repository offline