Get started with GitLab Orbit on GitLab Self-Managed

GitLab Orbit depends on three systems that it does not install: ClickHouse, Kubernetes, and NATS. The remaining setup steps require all three systems to exist and be reachable.

Prerequisites

• GitLab 19.2.2 or later.
• Administrator access to the GitLab instance and to its PostgreSQL server.
• A maintenance window for one PostgreSQL restart.
• ClickHouse 26.2 or later, set up for GitLab.
• Kubernetes 1.33 or later.
• NATS with JetStream turned on.

Installation order

Each step depends on the step before it. Install the components in this order:

1. Set up ClickHouse for GitLab and run the GitLab ClickHouse migrations.
2. Install NATS on the cluster with JetStream turned on.
3. Set up data replication: prepare PostgreSQL, then install Siphon. After this step, GitLab rows arrive in the ClickHouse data lake.
4. Set up GitLab Orbit: create the ClickHouse identities, install the chart, point GitLab at GitLab Orbit, and turn on indexing for a top-level group.

Steps 1 to 3 do not depend on GitLab Orbit. You can verify each one on its own.

ClickHouse

GitLab Orbit requires ClickHouse 26.2 or later, because the graph uses full-text indexes and materialized common table expressions introduced in that release. GitLab supports any 25.x or 26.x release, so a 25.x release serves the rest of GitLab but not GitLab Orbit. All other GitLab requirements for ClickHouse are unchanged.

Set up ClickHouse for GitLab first. For more information, see ClickHouse. Complete every step on that page, including Run ClickHouse migrations and Enable ClickHouse for analytics. Those migrations create the data lake tables that replication writes into. Without these tables, Siphon has no target to write to and replication fails.

GitLab Orbit uses two databases:

The two databases can be on separate ClickHouse instances. If they are, give GitLab, Siphon, and GitLab Orbit credentials for the instance that holds the database each one uses.

The gitlab_clickhouse_main_production database exists after ClickHouse setup is complete. You create the orbit database when you set up GitLab Orbit. GitLab Orbit does not create it at startup.

Sizing and settings

Provision at least 8 CPU and 32 GiB of memory for ClickHouse. ClickHouse saturates 8 cores while the graph builds.

Provision at least as much ClickHouse storage as the size of the GitLab PostgreSQL database.

A ClickHouse instance you run yourself sets max_bytes_before_external_sort and max_bytes_before_external_group_by to 0, which turns off spilling to disk. ClickHouse Cloud sets both to half of available memory. Without spilling, a large sort holds the whole result in memory and the server runs out of memory. Set both in the default profile. The following values suit a 32 GiB instance, with 8 GiB for each threshold and 20 GiB for the memory ceiling:

<profiles>
  <default>
    <max_bytes_before_external_sort>8589934592</max_bytes_before_external_sort>
    <max_bytes_before_external_group_by>8589934592</max_bytes_before_external_group_by>
    <max_memory_usage>21474836480</max_memory_usage>
  </default>
</profiles>

Kubernetes

GitLab Orbit requires Kubernetes 1.33 or later, with the ImageVolume feature gate turned on and supported by the container runtime.

GitLab Orbit can run on a separate cluster from GitLab. That cluster must reach GitLab, PostgreSQL, ClickHouse, and NATS, and GitLab must reach that cluster.

NATS

Siphon publishes every changed row to a NATS JetStream stream, and both Siphon and GitLab Orbit read from that stream. NATS requires JetStream turned on and a persistent volume.

Set the NATS server max_payload to 64 MB. The default of 1 MB is smaller than some GitLab rows. Siphon reads the server value to decide when a row is too large to send.

Object storage (optional)

Siphon stores snapshot events in an object store, along with any row that is still too large after you raise max_payload. By default, Siphon uses a NATS JetStream object store bucket, so no additional service is required. To keep that traffic off the JetStream volume, or to apply a separate retention policy, configure an S3-compatible or Google Cloud Storage bucket instead.

GitLab Orbit uses no object storage. The graph is stored in ClickHouse and can be rebuilt by indexing again. The indexer requires node-local disk for repository checkouts. The chart sizes this disk with ephemeral storage requests.

Shared configuration values

Choose each of these values once, and use the same value in every component that reads it. No component validates these values against the others. If they do not match, the affected component starts but processes no data.

GitLab Orbit expects the stream name siphon_stream_main_db by default. To use a different name, set stream_name in siphon-values.yaml and schedule.tasks.siphon.events_stream_name in orbit-values.yaml.

Next step

• Set up data replication