Supported Geo data types

A Geo data type is a specific class of data that is required by one or more GitLab features to store relevant information.

To replicate data produced by these features with Geo, we use several strategies to access, transfer, and verify them.

Data types

We distinguish between three different data types:

See the list below of each feature or component we replicate, its corresponding data type, replication, and verification methods:

TypeFeature / componentReplication methodVerification method
DatabaseApplication data in PostgreSQLNativeNative
DatabaseRedisNot applicable (1)Not applicable
DatabaseElasticsearchNativeNative
DatabaseSSH public keysPostgreSQL ReplicationPostgreSQL Replication
GitProject repositoryGeo with GitalyGitaly Checksum
GitProject wiki repositoryGeo with GitalyGitaly Checksum
GitProject designs repositoryGeo with GitalyGitaly Checksum
GitProject SnippetsGeo with GitalyGitaly Checksum
GitPersonal SnippetsGeo with GitalyGitaly Checksum
GitGroup wiki repositoryGeo with GitalyGitaly Checksum
BlobsUser uploads (file system) Geo with APISHA256 checksum
BlobsUser uploads (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsLFS objects (file system) Geo with APISHA256 checksum
BlobsLFS objects (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsCI job artifacts (file system) Geo with APISHA256 checksum
BlobsCI job artifacts (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsArchived CI build traces (file system) Geo with APINot implemented
BlobsArchived CI build traces (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsContainer registry (file system) Geo with API/Docker APISHA256 checksum
BlobsContainer registry (object storage) Geo with API/Managed/Docker API (2)SHA256 checksum (3)
BlobsPackage registry (file system) Geo with APISHA256 checksum
BlobsPackage registry (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsTerraform Module Registry (file system) Geo with APISHA256 checksum
BlobsTerraform Module Registry (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsVersioned Terraform State (file system) Geo with APISHA256 checksum
BlobsVersioned Terraform State (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsExternal Merge Request Diffs (file system) Geo with APISHA256 checksum
BlobsExternal Merge Request Diffs (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsPipeline artifacts (file system) Geo with APISHA256 checksum
BlobsPipeline artifacts (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsPages (file system) Geo with APISHA256 checksum
BlobsPages (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsCI Secure Files (file system) Geo with APISHA256 checksum
BlobsCI Secure Files (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsIncident Metric Images (file system) Geo with API/ManagedSHA256 checksum
BlobsIncident Metric Images (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsAlert Metric Images (file system) Geo with APISHA256 checksum
BlobsAlert Metric Images (object storage) Geo with API/Managed (2)SHA256 checksum (3)
BlobsDependency Proxy Images_(file system)_Geo with APISHA256 checksum
BlobsDependency Proxy Images (object storage) Geo with API/managed (2)SHA256 checksum (3)
  • (1): Redis replication can be used as part of HA with Redis sentinel. It’s not used between Geo sites.
  • (2): Object storage replication can be performed by Geo or by your object storage provider/appliance native replication feature.
  • (3): Object Storage verification is behind a feature flag, geo_object_storage_verification, introduced in 16.4 and enabled by default. It uses a checksum of the file size to verify the files.

Git repositories

A GitLab instance can have one or more repository shards. Each shard has a Gitaly instance that is responsible for allowing access and operations on the locally stored Git repositories. It can run on a machine:

  • With a single disk.
  • With multiple disks mounted as a single mount-point (like with a RAID array).
  • Using LVM.

GitLab does not require a special file system and can work with a mounted Storage Appliance. However, there can be performance limitations and consistency issues when using a remote file system.

Geo triggers garbage collection in Gitaly to deduplicate forked repositories on Geo secondary sites.

The Gitaly gRPC API does the communication, with three possible ways of synchronization:

  • Using regular Git clone/fetch from one Geo site to another (with special authentication).
  • Using repository snapshots (for when the first method fails or repository is corrupt).
  • Manual trigger from the Admin Area (a combination of both of the above).

Each project can have at most 3 different repositories:

  • A project repository, where the source code is stored.
  • A wiki repository, where the wiki content is stored.
  • A design repository, where design artifacts are indexed (assets are actually in LFS).

They all live in the same shard and share the same base name with a -wiki and -design suffix for Wiki and Design Repository cases.

Besides that, there are snippet repositories. They can be connected to a project or to some specific user. Both types are synced to a secondary site.

Blobs

GitLab stores files and blobs such as Issue attachments or LFS objects into either:

  • The file system in a specific location.
  • An Object Storage solution. Object Storage solutions can be:
    • Cloud based like Amazon S3 and Google Cloud Storage.
    • Hosted by you (like MinIO).
    • A Storage Appliance that exposes an Object Storage-compatible API.

When using the file system store instead of Object Storage, use network mounted file systems to run GitLab when using more than one node.

With respect to replication and verification:

  • We transfer files and blobs using an internal API request.
  • With Object Storage, you can either:
    • Use a cloud provider replication functionality.
    • Have GitLab replicate it for you.

Database

GitLab relies on data stored in multiple databases, for different use-cases. PostgreSQL is the single point of truth for user-generated content in the Web interface, like issues content, comments as well as permissions and credentials.

PostgreSQL can also hold some level of cached data like HTML-rendered Markdown and cached merge-requests diff. This can also be configured to be offloaded to object storage.

We use PostgreSQL’s own replication functionality to replicate data from the primary to secondary sites.

We use Redis both as a cache store and to hold persistent data for our background jobs system. Because both use-cases have data that are exclusive to the same Geo site, we don’t replicate it between sites.

Elasticsearch is an optional database for advanced search. It can improve search in both source-code level, and user generated content in issues, merge requests, and discussions. Elasticsearch is not supported in Geo.

Limitations on replication/verification

The following table lists the GitLab features along with their replication and verification status on a secondary site.

You can keep track of the progress to implement the missing items in these epics/issues:

Replicated data types behind a feature flag

The replication for some data types is behind a corresponding feature flag:

Version history
  • They’re deployed behind a feature flag, enabled by default.
  • They’re enabled on GitLab.com.
  • They can’t be enabled or disabled per-project.
  • They are recommended for production use.
  • For GitLab self-managed instances, GitLab administrators can opt to disable them.

Enable or disable replication (for some data types)

Replication for some data types are released behind feature flags that are enabled by default. GitLab administrators with access to the GitLab Rails console can opt to disable it for your instance. You can find feature flag names of each of those data types in the notes column of the table below.

To disable, such as for package file replication:

Feature.disable(:geo_package_file_replication)

To enable, such as for package file replication:

Feature.enable(:geo_package_file_replication)
caution
Features not on this list, or with No in the Replicated column, are not replicated to a secondary site. Failing over without manually replicating data from those features causes the data to be lost. To use those features on a secondary site, or to execute a failover successfully, you must replicate their data using some other means.
FeatureReplicated (added in GitLab version)Verified (added in GitLab version)GitLab-managed object storage replication (added in GitLab version)GitLab-managed object storage verification (added in GitLab version)Notes 
Application data in PostgreSQL Yes (10.2) Yes (10.2)Not applicableNot applicable  
Project repository Yes (10.2) Yes (10.7)Not applicableNot applicableMigrated to self-service framework in 16.2. See GitLab issue #367925 for more details.

Behind feature flag geo_project_repository_replication, enabled by default in (16.3).

All projects, including archived projects, are replicated.
 
Project wiki repository Yes (10.2)2 Yes (10.7)2 Not applicableNot applicableMigrated to self-service framework in 15.11. See GitLab issue #367925 for more details.

Behind feature flag geo_project_wiki_repository_replication, enabled by default in (15.11).
 
Group wiki repositoryYes (13.10)Yes (16.3)Not applicableNot applicableBehind feature flag geo_group_wiki_repository_replication, enabled by default. 
Uploads Yes (10.2) Yes (14.6)Yes (15.1)Yes (16.4)Replication is behind the feature flag geo_upload_replication, enabled by default. Verification was behind the feature flag geo_upload_verification, removed in 14.8. 
LFS objects Yes (10.2) Yes (14.6)Yes (15.1)Yes (16.4)GitLab versions 11.11.x and 12.0.x are affected by a bug that prevents any new LFS objects from replicating.

Replication is behind the feature flag geo_lfs_object_replication, enabled by default. Verification was behind the feature flag geo_lfs_object_verification, removed in 14.7.
 
Personal snippets Yes (10.2) Yes (10.2)Not applicableNot applicable  
Project snippets Yes (10.2) Yes (10.2)Not applicableNot applicable  
CI job artifacts Yes (10.4) Yes (14.10)Yes (15.1)Yes (16.4)Verification is behind the feature flag geo_job_artifact_replication, enabled by default in 14.10. 
CI Pipeline ArtifactsYes (13.11)Yes (13.11)Yes (15.1)Yes (16.4)Persists additional artifacts after a pipeline completes. 
CI Secure FilesYes (15.3)Yes (15.3)Yes (15.3)Yes (16.4)Verification is behind the feature flag geo_ci_secure_file_replication, enabled by default in 15.3. 
Container Registry Yes (12.3)1 Yes (15.10) Yes (12.3)1 Yes (15.10)See instructions to set up the Container Registry replication. 
Terraform Module Registry Yes (14.0) Yes (14.0)Yes (15.1)Yes (16.4)Behind feature flag geo_package_file_replication, enabled by default. 
Project designs repository Yes (12.7) Yes (16.1)Not applicableNot applicableDesigns also require replication of LFS objects and Uploads. 
Package Registry Yes (13.2) Yes (13.10)Yes (15.1)Yes (16.4)Behind feature flag geo_package_file_replication, enabled by default. 
Versioned Terraform State Yes (13.5) Yes (13.12)Yes (15.1)Yes (16.4)Replication is behind the feature flag geo_terraform_state_version_replication, enabled by default. Verification was behind the feature flag geo_terraform_state_version_verification, which was removed in 14.0. 
External merge request diffs Yes (13.5) Yes (14.6)Yes (15.1)Yes (16.4)Replication is behind the feature flag geo_merge_request_diff_replication, enabled by default. Verification was behind the feature flag geo_merge_request_diff_verification, removed in 14.7. 
Versioned snippetsYes (13.7)Yes (14.2)Not applicableNot applicableVerification was implemented behind the feature flag geo_snippet_repository_verification in 13.11, and the feature flag was removed in 14.2. 
GitLab PagesYes (14.3) Yes (14.6)Yes (15.1)Yes (16.4)Behind feature flag geo_pages_deployment_replication, enabled by default. Verification was behind the feature flag geo_pages_deployment_verification, removed in 14.7. 
Project-level Secure files Yes (15.3) Yes (15.3) Yes (15.3)Yes (16.4)  
Incident Metric Images Yes (15.5) Yes(15.5) Yes (15.5)Yes (16.4)Replication/Verification is handled via the Uploads data type. 
Alert Metric Images Yes (15.5) Yes (15.5) Yes (15.5)Yes (16.4)Replication/Verification is handled via the Uploads data type. 
Server-side Git hooksNot plannedNoNot applicableNot applicableNot planned because of current implementation complexity, low customer interest, and availability of alternatives to hooks. 
Elasticsearch integrationNot plannedNoNoNoNot planned because further product discovery is required and Elasticsearch (ES) clusters can be rebuilt. Secondaries use the same ES cluster as the primary. 
Dependency Proxy ImagesYes (15.7)Yes (15.7)Yes (15.7)Yes (16.4)  
Vulnerability ExportNot plannedNoNoNoNot planned because they are ephemeral and sensitive information. They can be regenerated on demand. 

1 Migrated to self-service framework in 15.5. See GitLab issue #337436 for more details.

2 Migrated to self-service framework in 15.11. Behind feature flag geo_project_wiki_repository_replication, enabled by default. See GitLab issue #367925 for more details.