Geo

EE-only multi-region replication. A "primary" GitLab handles all writes; one or more "secondary" sites replicate state and serve reads with low latency to nearby users. After a disaster, a secondary can be promoted to primary.

Source

ee/app/replicators/                  # One replicator per replicated resource
ee/app/services/geo/                 # Sync, verify, promote
ee/app/workers/geo/                  # Sync schedulers, verifiers
ee/app/models/geo_node.rb, geo_node_status.rb, geo_event.rb
ee/lib/gitlab/geo/                   # Core Geo abstractions
ee/lib/gitlab/geo/log_cursor/        # Tails the primary's event log
config/database.yml.decomposed-postgresql  # geo DB section
db/geo/                                # geo-tracking schema

How it works

graph LR
    Primary[Primary site]
    Secondary[Secondary site]
    GeoLog[(Geo Event Log<br/>on primary)]
    TrackDB[(Geo Tracking DB<br/>on secondary)]
    PSQL[(PostgreSQL streaming<br/>read replica)]

    Primary -->|writes| GeoLog
    Primary -->|streaming| PSQL
    PSQL -->|read| Secondary
    Secondary -->|tail| GeoLog
    GeoLog -->|tasks| TrackDB
    TrackDB --> Sync[Sync workers]
    Sync -->|fetch| Primary

Two separate replication channels:

1. PostgreSQL streaming replication for the application database. The secondary serves reads against this replica.
2. Geo replication for everything else — Git repos, LFS objects, CI artifacts, package files, container images, security findings, container registry. The primary writes a row to geo_event_log for each change; the secondary's "log cursor" reads this and creates Geo::ProjectRepositoryRegistry (etc.) tasks for sync.

Replicators

A Replicator registers a resource type with Geo. Each replicator:

• Defines a primary-side event creator (Geo::Event).
• Defines a secondary-side fetcher (Geo::ReplicableSyncService).
• Defines verification (compare checksum or content hash).
• Maps to a *_states registry table.

Examples:

• Geo::ProjectRepositoryReplicator
• Geo::ContainerRepositoryReplicator
• Geo::LfsObjectReplicator
• Geo::PackageFileReplicator
• Geo::SecurityFindingReplicator

Verification

Each replicator records a checksum on the primary and verifies after sync on the secondary. The Geo dashboard shows per-resource sync and verify counts.

Selective sync

Operators can configure secondaries to sync only specific groups, namespaces, or shards. The model GeoNode stores the policy.

Failover and promotion

When the primary fails, a secondary can be promoted via:

• gitlab-ctl promote-to-primary-node (Omnibus).
• The "Promote" UI in the Geo admin.

Promotion involves stopping the secondary's log cursor, switching the database role, and re-pointing pipelines.

Disaster recovery (DR)

Geo is the official DR strategy for self-managed customers. Documentation lives at https://docs.gitlab.com/ee/administration/geo/.

Where to add a new replicator

1. Create ee/app/replicators/geo/<resource>_replicator.rb with checksum and fetch logic.
2. Add a geo_<resource>_registry table via a tracking-DB migration.
3. Add a Sidekiq worker if the sync is non-trivial.
4. Update the verifier and the dashboard view.

Related

• Database — Postgres streaming + tracking DB.
• Object storage — replicated blobs.
• Sidekiq jobs — sync workers.