Connect your agent to GitLab Orbit
- Tier: Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
The GitLab Orbit CLI connects the agents on your machine to GitLab Orbit. The GitLab Orbit skill teaches your agent to query your GitLab data, such as merge requests, pipelines, and vulnerabilities, and the local graph.
GitLab Duo Agent Platform has GitLab Orbit built in. For more information, see GitLab Orbit in GitLab Duo. For agents that cannot run shell commands or that prefer the Model Context Protocol (MCP), use the GitLab Orbit MCP endpoint. If your agent already connects to the GitLab MCP server, add the GitLab Orbit tools to that connection.
Set up your agent
Use the GitLab CLI (glab) to install the GitLab Orbit CLI and set up your agents.
For a short walkthrough, see the quickstart.
Prerequisites:
glab1.126 or later. To check your version, runglab version.- An agent that setup supports. For the list, see setup options.
To set up your agent:
- Go to a Git repository on your machine. Any repository works.
- Run
glab orbit setup. On first use,glabasks to download the GitLab Orbit CLI. - In the list of agents, keep or clear the agents that setup selected, then press Enter.
- When setup asks about the agent plugins, choose whether to install them, then press Enter. The plugins are optional. GitLab Orbit works the same without them. To install them, keep Install the agent plugins selected. To leave them out, select Skip the agent plugins.
Setup installs the GitLab Orbit skill for your agents and, unless you skip them, agent plugins that show GitLab Orbit calls in Claude Code and OpenCode.
It then indexes the repository for code search.
To check that the repository is indexed, run glab orbit workspace list.
To load the skill, start a new session of your agent.
To update the setup, run the command again.
For a guided first session, see step 3 of the quickstart.
To run setup without a terminal, for example from an agent or a script, confirm the prompts with --yes:
glab orbit --yes setup --yesThe first --yes confirms the download. The second skips the setup prompts and installs the agent plugins.
To leave out the agent plugins, add --skip agent-plugins.
To query your GitLab data, also sign in with glab.
If you installed the standalone binary, run orbit in place of glab orbit.
Setup options
Setup supports Claude Code (claude), Codex (codex), GitLab Duo (duo), OpenCode (opencode), and Pi (pi).
By default, setup selects the agents it detects on your machine.
glab orbit setup [<agent>...] [options]| Option | Description |
|---|---|
<agent> | Set up only these agents, for example claude codex. Setup adds a named agent even when it does not detect it. |
--all | Set up every supported agent. |
--yes, -y | Skip the prompts and use the default answers. |
--skip <component> | Leave out instructions, hooks, skill, or agent-plugins. You can repeat it. |
--install <component> | Add a component without a prompt, for example --install agent-plugins. You can repeat it. |
--skill full | Install the full skill files in place of the wrapper skill. |
--no-index | Do not index the repository. |
--project | Write to the current project in place of your user configuration. |
--dir <path> | Write to the project in <path>. Implies --project. |
--dry-run | Show the changes and write nothing. |
--verbose, -v | List every file setup changes. |
Changes setup makes
By default, setup writes to your user configuration, so the changes affect only you.
| Component | Agents | Changes |
|---|---|---|
| Instructions | All | Each new session loads instructions to search with orbit grep and read code with orbit context. Setup removes the block an earlier setup wrote to CLAUDE.md or AGENTS.md. |
| Hooks | Claude Code, Codex, GitLab Duo, OpenCode, Pi | The hooks that load the instructions, and a reminder to use orbit grep. For Claude Code, the reminder comes when the agent runs grep, rg, ack, or ag in an indexed repository, and never blocks the call. For OpenCode, the reminder comes once each session. |
| Skill | Claude Code, Codex, GitLab Duo, OpenCode | The orbit skill, in ~/.agents/skills/orbit. For GitLab Duo, setup writes the full skill files. For Claude Code, setup also links the skill in ~/.claude/skills/, and allows the skill command in settings.json so that the skill loads without a prompt. |
| Agent plugins | Claude Code, OpenCode | A plugin that shows each GitLab Orbit call. For Claude Code, setup installs the gitlab-orbit plugin in ~/.claude/orbit/claude_plugin and turns it on in settings.json, or in .claude/settings.local.json with --project. For OpenCode, setup installs the orbit-ui plugin in ~/.config/opencode/plugins/orbit-ui/. |
Other agents that support the Agent Skills specification, such as Gemini CLI,
can also load the skill from ~/.agents/skills/orbit.
By default, setup installs a wrapper skill that loads the skill your GitLab instance serves, so the skill always matches your instance. If the CLI cannot get the skill from your instance, it uses the copy built into the CLI.
Your instance also serves the orbit-start skill, which walks you through a first session.
Setup does not install it. An agent loads it with glab orbit skills get orbit-start.
For the prompt, see step 3 of the quickstart.
Setup follows these rules:
- Setup changes only the text between its markers and the entries it marked as its own.
- Before setup changes a file for the first time, it saves a copy as
<name>.orbit-backup. - Setup sets the
glaboptionorbit_cli_auto_runtotruefor the repository where you run it, so the hooks run without a prompt. To set it for every repository, runglab config set orbit_cli_auto_run true --global. - With
--projector--dir, setup writes files such as.claude/settings.json,.codex/hooks.json,.gitlab/duo/hooks.json, and.pi/extensions/orbit.tsin the project. Teams usually commit these files, so the change can reach your teammates.
Show GitLab Orbit calls in your agent
glab orbit setup can install optional agent plugins for Claude Code and OpenCode that show each GitLab Orbit call and a summary of the session’s calls:
- In Claude Code, the plugin marks each call in the transcript, for example
◎ Searched code login, and shows the summary below the prompt. - In OpenCode, the plugin shows the latest call above the prompt and the summary in the prompt footer.
Prerequisites:
- For Claude Code, version 2.1.287 or later.
To install the plugins, run glab orbit setup and select Install the agent plugins.
Then start a new session of your agent.
To turn off the plugin:
- In Claude Code, run
/pluginand turn offgitlab-orbit. - In OpenCode, delete the
~/.config/opencode/plugins/orbit-ui/directory.
Remove the setup
To remove what setup wrote, including the orbit skill and the ~/.claude/skills/orbit link, run:
glab orbit uninstallThe command leaves the rest of each file unchanged.
If you edited a file after setup, the command keeps the file and its backup.
It accepts the same agent names and the --yes, --dry-run, --verbose, --project, and --dir options as setup.