Tuning Geo

You can limit the number of concurrent operations the sites can run in the background.

Changing the sync/verification concurrency values

On the primary site:

1. In the upper-right corner, select Admin.

2. In the left sidebar, select Geo > Sites.

3. Select Edit of the secondary site you want to tune.

4. Under Tuning settings, there are several variables that can be tuned to improve the performance of Geo:

   • Repository synchronization concurrency limit
   • File synchronization concurrency limit
   • Container repositories synchronization concurrency limit
   • Verification concurrency limit

Increasing the concurrency values increases the number of jobs that are scheduled. However, this may not lead to more downloads in parallel unless the number of available Sidekiq threads is also increased. For example, if repository synchronization concurrency is increased from 25 to 50, you may also want to increase the number of Sidekiq threads from 25 to 50. See the Sidekiq concurrency documentation for more details.

Tuning low default settings

To avoid excessive load when setting up new Geo sites, starting with GitLab 18.0, Geo’s concurrency settings are set to low defaults for most environments. To increase these settings:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Geo > Sites.
3. Decide which data types are progressing too slowly.
4. Watch load metrics of the primary and secondary sites.
5. Increase concurrency limits by 10 to be conservative.
6. Watch changes in progress and load metrics for at least 3 minutes.
7. Repeat increasing the limits until either load metrics reach your desired maximum, or syncing and verification is progressing as quickly as desired.

Reduce the amount of replicated data

Every file retained on the primary site must be stored, synced, and verified on every secondary site, and counted by Geo metrics collection. Deleting data that provides no value is often more effective than increasing concurrency, and it also shortens the initial sync when you add or rebuild a secondary site.

CI/CD job artifacts are usually the largest contributor. To reduce their volume:

• Make sure artifacts expire. Artifacts are deleted automatically after the default artifacts expiration (30 days by default), or after the duration set per job with artifacts:expire_in. When an artifact expires, GitLab permanently deletes the file and its database records, and publishes Geo delete events so that each secondary site removes its synced copy and its registry entry. Smaller tables directly reduce sync, verification, and Geo metrics collection load.
• Review the Keep artifacts from latest successful pipelines setting. When enabled, artifacts of the most recent successful pipeline for each Git ref never expire. On instances with many active branches and tags, this setting can retain a large number of artifacts indefinitely.
• Clean up artifacts that have no expiry. Artifacts created before an expiry policy was in place have no expiration date and are never deleted by the expiry workers. To find and remove them, see list projects and builds with artifacts with a specific expiration (or no expiration) and delete old builds and artifacts. To remove artifact files left on disk without database records, use the orphan artifact file cleanup Rake task.

The same principle applies to other replicated data types, such as LFS objects and package files. For container registry images, use cleanup policies.

Repository re-verification

See Automatic background verification.