Get started with GitLab Orbit Remote

  • Tier: Premium, Ultimate
  • Offering: GitLab.com
  • Status: Beta

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.

Prerequisites

  • 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.

Step 1: Enable GitLab Orbit

  1. On the left sidebar, expand Your Work.
  2. Select Orbit > Configuration.
  3. Find your top-level group in the Indexes list.
  4. 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 status

Step 2: Run your first query

GitLab 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 Duo Agent Platform (no setup required)

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 query_graph and get_graph_schema tools automatically 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.

MCP (Claude Code, Codex, other agents)

See Use GitLab Orbit via MCP for setup. Once configured, you have two tools: query_graph and get_graph_schema.

Install the GitLab Orbit skill for AI agents

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 orbit

See Set up AI coding agents with the GitLab Orbit skill for project-scoped install, update instructions, and what the skill contains.

REST API

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": {"op": "starts_with", "value": "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 to try next