Setting up Geo


  • Two (or more) independently working GitLab sites:
    • One GitLab site serves as the Geo primary site. Use the GitLab reference architectures documentation to set this up. You can use different reference architecture sizes for each Geo site. If you already have a working GitLab instance that is in-use, it can be used as a primary site.
    • The second GitLab site serves as the Geo secondary site. Use the GitLab reference architectures documentation to set this up. It’s a good idea to sign in and test it. However, be aware that all of the data on the secondary are lost as part of the process of replicating from the primary site.
    Geo supports multiple secondaries. You can follow the same steps and make any changes accordingly.
  • Ensure the primary site has a GitLab Premium or Ultimate subscription to unlock Geo. You only need one license for all the sites.
  • Confirm the requirements for running Geo are met by all sites. For example, sites must use the same GitLab version, and sites must be able to communicate with each other over certain ports.
  • Confirm the primary and secondary site storage configurations match. If the primary Geo site uses object storage, the secondary Geo site must use it too. For more information, see Geo with Object storage.
  • Ensure clocks are synchronized between the primary site and the secondary site. Synchronized clocks are required for Geo to function correctly. For example, if the clock drift between the primary and secondary sites exceeds 1 minute, replication fails.

Using Omnibus GitLab

If you installed GitLab using the Omnibus packages (highly recommended), the process for setting up Geo depends on whether you need to set up a single-node Geo site or a multi-node Geo site.

Single-node Geo sites

If both Geo sites are based on the 1K reference architecture:

  1. Set up the database replication (primary (read-write) <-> secondary (read-only) topology).
  2. Configure GitLab to set the primary and secondary sites.
  3. Optional: Configure Object storage
  4. Optional: Configure a secondary LDAP server for the secondary sites. See notes on LDAP.
  5. Optional: Configure Geo secondary proxying to use a single, unified URL for all Geo sites. This step is recommended to accelerate most read requests while transparently proxying writes to the primary Geo site.
  6. Optional: Configure Container Registry for the secondary site.
  7. Follow the Using a Geo Site guide.

Multi-node Geo sites

If one or more of your sites is using the 2K reference architecture or larger, see Configure Geo for multiple nodes.

Using GitLab Charts

Configure the GitLab chart with GitLab Geo.

Geo and self-compiled installations

Geo is not supported when you use a self-compiled GitLab installation.

Post-installation documentation

After installing GitLab on the secondary sites and performing the initial configuration, see the following documentation for post-installation information.