Skip to content

getting-started.md

Latest commit

 

History

History
211 lines (147 loc) · 6.6 KB

getting-started.md

File metadata and controls

211 lines (147 loc) · 6.6 KB
Raw
stage Orbit
group Context Systems
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 Pick an access method and build your first local GitLab Orbit graph.
title Get started with GitLab Orbit Local

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Beta

{{< /details >}}

{{< history >}}

{{< /history >}}

GitLab Orbit Local runs on your machine. Install the orbit binary, pick the access method that matches how you work, then run your first query.

Install

Install the orbit binary directly with the one-line installer, from npm, or through the GitLab CLI (glab) if you already use it.

On Linux, the installer uses the glibc archive by default. The glibc archive needs glibc 2.28 or later. It runs on RHEL 8, Oracle Linux 8, Debian 10, Ubuntu 20.04, and later releases. On musl-based distributions like Alpine, the installer selects the fully static musl archive. On older glibc, pass --libc musl to force the static archive.

{{< tabs >}}

{{< tab title="macOS and Linux" >}}

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash

To explicitly install the static musl binary (e.g. on a glibc system):

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash -s -- --libc musl

Open a new terminal, then verify:

orbit help

{{< /tab >}}

{{< tab title="Windows" >}}

irm https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.ps1 | iex

Open a new terminal, then verify:

orbit help

If your endpoint policy restricts remote script execution, you can install without running any script. The Windows release archive contains a single self-contained orbit.exe, signed by GitLab Inc., so application allowlisting policies can authorize it by publisher:

  1. From the latest release, download orbit-cli-windows-x86_64.zip and its .sha256 file.

  2. Verify the checksum:

    (Get-FileHash .\orbit-cli-windows-x86_64.zip -Algorithm SHA256).Hash

    The output must match the hash in the .sha256 file. The comparison is not case-sensitive: Get-FileHash returns uppercase and the .sha256 file stores lowercase.

  3. Clear the Mark of the Web. A browser attaches it to the download, extraction carries it to orbit.exe, and the first run can then raise a SmartScreen prompt or be blocked by policy:

    Unblock-File .\orbit-cli-windows-x86_64.zip

  4. Extract the archive, create the target directory, then move orbit.exe into it. This example uses $env:LOCALAPPDATA\Programs\orbit, the same default the installer uses:

    Expand-Archive -Path .\orbit-cli-windows-x86_64.zip -DestinationPath .
New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\Programs\orbit"
Move-Item .\orbit.exe "$env:LOCALAPPDATA\Programs\orbit\orbit.exe"

  5. If that directory is not already on your PATH, add it for your user:

    [Environment]::SetEnvironmentVariable("PATH", "$env:LOCALAPPDATA\Programs\orbit;$([Environment]::GetEnvironmentVariable('PATH', 'User'))", "User")

No administrator rights are required.

Open a new terminal, then verify:

orbit help

{{< /tab >}}

{{< tab title="npm" >}}

You can also install from npm, on any platform:

npm install -g @gitlab/orbit

The @gitlab/orbit package installs the prebuilt binary for your platform. On Linux, it always uses the fully static musl binary, which runs on both glibc and musl distributions.

Verify:

orbit help

{{< /tab >}}

{{< tab title="GitLab CLI (glab)" >}}

If you already have glab installed:

glab orbit --install

Verify:

glab orbit help

See the glab orbit reference for details.

{{< /tab >}}

{{< /tabs >}}

Pick an access method

Method Best for Setup
The GitLab Orbit CLI (orbit) Direct CLI use, scripting, indexing tasks One-line installer or glab orbit --install
The GitLab CLI (glab) Anyone already using glab glab orbit --install
MCP Claude Code, Codex, and other AI agents claude mcp add orbit-cli -- orbit mcp serve

All three read the same local graph. GitLab Orbit Local is queried with DuckDB SQL; the structured JSON query DSL is GitLab Orbit Remote only.

60-second quickstart

Note

glab orbit wraps the managed orbit binary. The binary downloads, is checksum-verified, and stays up to date on first use. Requires glab 1.117 or later. To run the binary directly instead, see Use the orbit CLI directly.

Index a repository and inspect what GitLab Orbit found:

glab orbit index /path/to/your/repo
glab orbit schema

That builds a revision graph under ~/.gitlab/orbit/local/ and prints every table and column in it: gl_definition, gl_file, gl_directory, gl_imported_symbol, gl_edge, and the _orbit_manifest bookkeeping table.

Next:

Billing

GitLab Orbit Local does not consume GitLab Credits. All processing is local.

What to try next