Configure Gitaly

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

Configure Gitaly in one of two ways:

Edit /etc/gitlab/gitlab.rb and add or change the Gitaly settings. Refer to the example Gitaly configuration file. The settings in the example file must be converted into Ruby.
Save the file and reconfigure GitLab.

Configure the Gitaly chart.
Upgrade your Helm release.

Edit /home/git/gitaly/config.toml and add or change the Gitaly settings. Refer to the example Gitaly configuration file.
Save the file and restart GitLab.

The following configuration options are also available:

Enabling TLS support.
Limiting RPC concurrency.
Limiting pack-objects concurrency.

About the Gitaly token

The token referred to throughout the Gitaly documentation is just an arbitrary password selected by the administrator. It is unrelated to tokens created for the GitLab API or other similar web API tokens.

Run Gitaly on its own server

By default, Gitaly is run on the same server as Gitaly clients and is configured as described previously. Single-server installations are best served by this default configuration used by:

However, Gitaly can be deployed to its own server, which can benefit GitLab installations that span multiple machines.

[!note] When configured to run on their own servers, Gitaly servers must be upgraded before Gitaly clients in your cluster.

The process for setting up Gitaly on its own server is:

Install Gitaly.
Configure authentication.
Configure Gitaly servers.
Configure Gitaly clients.
Disable Gitaly where not required (optional).

[!note] Disk requirements apply to Gitaly nodes.

Network architecture

The following list depicts the network architecture of Gitaly:

GitLab Rails shards repositories into repository storages.
/config/gitlab.yml contains a map from storage names to (Gitaly address, Gitaly token) pairs.
The storage name -> (Gitaly address, Gitaly token) map in /config/gitlab.yml is the single source of truth for the Gitaly network topology.
A (Gitaly address, Gitaly token) corresponds to a Gitaly server.
A Gitaly server hosts one or more storages.
A Gitaly client can use one or more Gitaly servers.
Gitaly addresses must be specified in such a way that they resolve correctly for all Gitaly clients.
Gitaly clients are:
- Puma.
- Sidekiq.
- GitLab Workhorse.
- GitLab Shell.
- Elasticsearch indexer.
- Gitaly itself.
A Gitaly server must be able to make RPC calls to itself by using its own (Gitaly address, Gitaly token) pair as specified in /config/gitlab.yml.
Authentication is done through a static token which is shared among the Gitaly and GitLab Rails nodes.

The following diagram illustrates communication between Gitaly servers and GitLab Rails showing the default ports for HTTP and HTTPs communication.

[!warning] Gitaly servers must not be exposed to the public internet as Gitaly network traffic is unencrypted by default. The use of firewall is highly recommended to restrict access to the Gitaly server. Another option is to use TLS.

In the following sections, we describe how to configure two Gitaly servers with secret token abc123secret:

gitaly1.internal.
gitaly2.internal.

We assume your GitLab installation has three repository storages:

default.
storage1.
storage2.

You can use as few as one server with one repository storage if desired.

Install Gitaly

Install Gitaly on each Gitaly server using either:

A Linux package installation. Download and install the Linux package you want but do not provide the EXTERNAL_URL= value.
A self-compiled installation. Follow the steps at Install Gitaly.

Configure Gitaly servers

To configure Gitaly servers, you must:

Configure authentication.
Configure storage paths.
Enable the network listener.

The git user must be able to read, write, and set permissions on the configured storage path.

To avoid downtime while rotating the Gitaly token, you can temporarily disable authentication using the gitaly['auth_transitioning'] setting. For more information, see enable auth transitioning mode.

Configure authentication

Support for token_file introduced in GitLab 18.11.

Gitaly and GitLab use two shared secrets for authentication:

Gitaly token: used to authenticate gRPC requests to Gitaly. You can specify the Gitaly token directly in GitLab configuration or in a token file. Using a token file is more secure and better suited to containerized environments because it avoids rendering secrets into the configuration at startup time. The token file must:
- Contain only the token string. Whitespace is trimmed automatically.
- Have file permissions 0600 or 0400.
GitLab Shell token: used for authentication callbacks from GitLab Shell to the GitLab internal API.

To configure the Gitaly token, edit /etc/gitlab/gitlab.rb:

When using a token file:

ruby

gitaly['configuration'] = {
   # ...
   auth: {
     # ...
     token_file: '/etc/gitlab/gitaly_token',
   },
}

When specifying the token directly:

ruby

gitaly['configuration'] = {
   # ...
   auth: {
     # ...
     token: 'abc123secret',
   },
}

token and token_file are mutually exclusive.

Configure the GitLab Shell token in one of two ways:
- Method 1 (recommended): copy /etc/gitlab/gitlab-secrets.json from the Gitaly client to the same path on the Gitaly servers and any other Gitaly clients.
- Method 2:
  1. On all nodes running GitLab Rails, edit /etc/gitlab/gitlab.rb.
  2. Replace GITLAB_SHELL_SECRET_TOKEN with the real secret:
    - GitLab 17.5 and later:
      ruby
      gitaly['gitlab_secret'] = 'GITLAB_SHELL_SECRET_TOKEN'
    - GitLab 17.4 and earlier:
      ruby
      gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
  3. On all nodes running Gitaly, edit /etc/gitlab/gitlab.rb.
  4. Replace GITLAB_SHELL_SECRET_TOKEN with the real secret:
    - GitLab 17.5 and later:
      ruby
      gitaly['gitlab_secret'] = 'GITLAB_SHELL_SECRET_TOKEN'
    - GitLab 17.4 and earlier:
      ruby
      gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
  5. After those changes, reconfigure GitLab:
  shell
```
sudo gitlab-ctl reconfigure
```

Copy /home/git/gitlab/.gitlab_shell_secret from the Gitaly client to the same path on the Gitaly servers (and any other Gitaly clients).
On the Gitaly clients, edit /home/git/gitlab/config/gitlab.yml:
yaml
```
gitlab:
  gitaly:
    token: 'abc123secret'
```
Save the file and restart GitLab.
On the Gitaly servers, edit /home/git/gitaly/config.toml:
- When using a token file:
  toml
```
[auth]
token_file = '/etc/gitaly/token'
```
- When specifying the token directly:
  toml
```
[auth]
token = 'abc123secret'
```
token and token_file are mutually exclusive.
Save the file and restart GitLab.

Configure Gitaly server

Configure Gitaly server.

Gitaly has some RPCs in which it makes a network call to itself using the address provided by the client (such as Rails or Sidekiq).

If Gitaly can't reach itself this way because of your network configuration (for example, Gitaly is behind a load balancer that doesn't support hairpinning connections):

Edit the /etc/hosts file of the Gitaly server.
Add an entry for redirecting the Gitaly address used by clients to the Gitaly server's own IP address. For example, 127.0.0.1 gitaly.example.com or <local-ip> gitaly.example.com.

Edit /etc/gitlab/gitlab.rb:

ruby

# Avoid running unnecessary services on the Gitaly server
postgresql['enable'] = false
redis['enable'] = false
nginx['enable'] = false
puma['enable'] = false
sidekiq['enable'] = false
gitlab_workhorse['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false

# If you run a separate monitoring node you can disable these services
prometheus['enable'] = false
alertmanager['enable'] = false

# If you don't run a separate monitoring node you can
# enable Prometheus access & disable these extra services.
# This makes Prometheus listen on all interfaces. You must use firewalls to restrict access to this address/port.
# prometheus['listen_address'] = '0.0.0.0:9090'
# prometheus['monitor_kubernetes'] = false

# If you don't want to run monitoring services uncomment the following (not recommended)
# node_exporter['enable'] = false

# Prevent database connections during 'gitlab-ctl reconfigure'
gitlab_rails['auto_migrate'] = false

# Configure the gitlab-shell API callback URL. Without this, `git push` will
# fail. This can be your 'front door' GitLab URL or an internal load
# balancer.
# Don't forget to copy `/etc/gitlab/gitlab-secrets.json` from Gitaly client to Gitaly server.
gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'

gitaly['configuration'] = {
   # ...
   #
   # Make Gitaly accept connections on all network interfaces. You must use
   # firewalls to restrict access to this address/port.
   # Comment out following line if you only want to support TLS connections
   listen_addr: '0.0.0.0:8075',
   auth: {
     # ...
     #
     # Authentication token to ensure only authorized servers can communicate with
     # Gitaly server
     token: 'AUTH_TOKEN',
   },
}

Append the following to /etc/gitlab/gitlab.rb for each respective Gitaly server:

On gitaly1.internal:

ruby

gitaly['configuration'] = {
   # ...
   storage: [
      {
         name: 'default',
         path: '/var/opt/gitlab/git-data/repositories',
      },
      {
         name: 'storage1',
         path: '/mnt/gitlab/git-data/repositories',
      },
   ],
}

On gitaly2.internal:

ruby

gitaly['configuration'] = {
   # ...
   storage: [
      {
         name: 'storage2',
         path: '/srv/gitlab/git-data/repositories',
      },
   ],
}

Save the file and reconfigure GitLab.

Confirm that Gitaly can perform callbacks to the GitLab internal API:

shell

sudo -u git -- /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml

Edit /home/git/gitaly/config.toml:

toml

listen_addr = '0.0.0.0:8075'

runtime_dir = '/var/opt/gitlab/gitaly'

[logging]
format = 'json'
level = 'info'
dir = '/var/log/gitaly'

Append the following to /home/git/gitaly/config.toml for each respective Gitaly server:

On gitaly1.internal:

toml

[[storage]]
name = 'default'
path = '/var/opt/gitlab/git-data/repositories'

[[storage]]
name = 'storage1'
path = '/mnt/gitlab/git-data/repositories'

On gitaly2.internal:

toml

[[storage]]
name = 'storage2'
path = '/srv/gitlab/git-data/repositories'

Edit /home/git/gitlab-shell/config.yml:
yaml
```
gitlab_url: https://gitlab.example.com
```
Save the files and restart GitLab.

Confirm that Gitaly can perform callbacks to the GitLab internal API:

shell

sudo -u git -- /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml

[!warning] If directly copying repository data from a GitLab server to Gitaly, ensure that the metadata file, default path /var/opt/gitlab/git-data/repositories/.gitaly-metadata, is not included in the transfer. Copying this file causes GitLab to use the direct disk access to repositories hosted on the Gitaly server, leading to Error creating pipeline and Commit not found errors, or stale data.

Configure Gitaly clients

As the final step, you must update Gitaly clients to switch from using local Gitaly service to use the Gitaly servers you just configured.

[!note] GitLab requires a default repository storage to be configured. Read more about this limitation.

This can be risky because anything that prevents your Gitaly clients from reaching the Gitaly servers causes all Gitaly requests to fail. For example, any sort of network, firewall, or name resolution problems.

Gitaly makes the following assumptions:

Your gitaly1.internal Gitaly server can be reached at gitaly1.internal:8075 from your Gitaly clients, and that Gitaly server can read, write, and set permissions on /var/opt/gitlab/git-data and /mnt/gitlab/git-data.
Your gitaly2.internal Gitaly server can be reached at gitaly2.internal:8075 from your Gitaly clients, and that Gitaly server can read, write, and set permissions on /srv/gitlab/git-data.
Your gitaly1.internal and gitaly2.internal Gitaly servers can reach each other.

You can't define Gitaly servers with some as a local Gitaly server (without gitaly_address) and some as remote server (with gitaly_address) unless you use mixed configuration.

Configure Gitaly clients in one of two ways. These instructions are for unencrypted connections but you can also enable TLS support:

Edit /etc/gitlab/gitlab.rb:

ruby

# Use the same token value configured on all Gitaly servers
gitlab_rails['gitaly_token'] = '<AUTH_TOKEN>'

gitlab_rails['repositories_storages'] = {
  'default'  => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  'storage1' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
}

Alternatively, if each Gitaly server is configured to use a different authentication token:

ruby

gitlab_rails['repositories_storages'] = {
  'default'  => { 'gitaly_address' => 'tcp://gitaly1.internal:8075', 'gitaly_token' => '<AUTH_TOKEN_1>' },
  'storage1' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075', 'gitaly_token' => '<AUTH_TOKEN_1>' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075', 'gitaly_token' => '<AUTH_TOKEN_2>' },
}

Save the file and reconfigure GitLab.
Run sudo gitlab-rake gitlab:gitaly:check on the Gitaly client (for example, the Rails application) to confirm it can connect to Gitaly servers.
Tail the logs to see the requests:
shell
```
sudo gitlab-ctl tail gitaly
```

Edit /home/git/gitlab/config/gitlab.yml:

yaml

gitlab:
  repositories:
    storages:
      default:
        gitaly_address: tcp://gitaly1.internal:8075
        gitaly_token: AUTH_TOKEN_1
      storage1:
        gitaly_address: tcp://gitaly1.internal:8075
        gitaly_token: AUTH_TOKEN_1
      storage2:
        gitaly_address: tcp://gitaly2.internal:8075
        gitaly_token: AUTH_TOKEN_2

Save the file and restart GitLab.
Run sudo -u git -H bundle exec rake gitlab:gitaly:check RAILS_ENV=production to confirm the Gitaly client can connect to Gitaly servers.
Tail the logs to see the requests:
shell
```
tail -f /home/git/gitlab/log/gitaly.log
```

When you tail the Gitaly logs on your Gitaly server, you should see requests coming in. One sure way to trigger a Gitaly request is to clone a repository from GitLab over HTTP or HTTPS.

[!warning] If you have server hooks configured, either per repository or globally, you must move these to the Gitaly servers. If you have multiple Gitaly servers, copy your server hooks to all Gitaly servers.

Mixed configuration

GitLab can reside on the same server as one of many Gitaly servers, but doesn't support configuration that mixes local and remote configuration. The following setup is incorrect, because:

All addresses must be reachable from the other Gitaly servers.
storage1 is assigned a Unix socket for gitaly_address which is invalid for some of the Gitaly servers.

ruby

gitlab_rails['repositories_storages'] = {
  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  'storage1' => { 'gitaly_address' => 'unix:/var/opt/gitlab/gitaly/gitaly.socket' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
}

To combine local and remote Gitaly servers, use an external address for the local Gitaly server. For example:

ruby

gitlab_rails['repositories_storages'] = {
  'default' => { 'gitaly_address' => 'tcp://gitaly1.internal:8075' },
  # Address of the GitLab server that also has Gitaly running on it
  'storage1' => { 'gitaly_address' => 'tcp://gitlab.internal:8075' },
  'storage2' => { 'gitaly_address' => 'tcp://gitaly2.internal:8075' },
}

gitaly['configuration'] = {
  # ...
  #
  # Make Gitaly accept connections on all network interfaces
  listen_addr: '0.0.0.0:8075',
  # Or for TLS
  tls_listen_addr: '0.0.0.0:9999',
  tls: {
    certificate_path:  '/etc/gitlab/ssl/cert.pem',
    key_path: '/etc/gitlab/ssl/key.pem',
  },
  storage: [
    {
      name: 'storage1',
      path: '/mnt/gitlab/git-data/repositories',
    },
  ],
}

path can be included only for storage shards on the local Gitaly server. If it's excluded, default Git storage directory is used for that storage shard.

GitLab requires a default repository storage

When adding Gitaly servers to an environment, you might want to replace the original default Gitaly service. However, you can't reconfigure the GitLab application servers to remove the default storage because GitLab requires a storage called default. Read more about this limitation.

To work around the limitation:

Define an additional storage location on the new Gitaly service and configure the additional storage to be default. The storage location must have a Gitaly service running and available to avoid issues with database migrations that expect working storages.
In the Admin area, set default to a weight of zero to prevent repositories being stored there.

Disable Gitaly where not required (optional)

If you run Gitaly as a remote service, consider disabling the local Gitaly service that runs on your GitLab server by default, and run it only where required.

Disabling Gitaly on the GitLab instance makes sense only when you run GitLab in a custom cluster configuration, where Gitaly runs on a separate machine from the GitLab instance. Disabling Gitaly on all machines in the cluster is not a valid configuration (some machines much act as Gitaly servers).

Disable Gitaly on a GitLab server in one of two ways:

Edit /etc/gitlab/gitlab.rb:
ruby
```
gitaly['enable'] = false
```
Save the file and reconfigure GitLab.

Edit /etc/default/gitlab:
shell
```
gitaly_enabled=false
```
Save the file and restart GitLab.

Change the Gitaly listening interface

You can change the interface that Gitaly listens on. You might change the listening interface when you have an external service that must communicate with Gitaly. For example, exact code search that uses Zoekt when exact code search is enabled but the actual service is running on another server.

The gitaly_token must be a secret string because gitaly_token is used for authentication with the Gitaly service. This secret can be generated with openssl rand -base64 24 to generate a random 32 character string.

For example, to change the Gitaly listening interface to 0.0.0.0:8075:

ruby

# /etc/gitlab/gitlab.rb
# Add a shared token for Gitaly authentication
gitlab_shell['secret_token'] = 'your_secure_token_here'
gitlab_rails['gitaly_token'] = 'your_secure_token_here'

# Gitaly configuration
gitaly['gitlab_secret'] = 'your_secure_token_here'
gitaly['configuration'] = {
  listen_addr: '0.0.0.0:8075',
  auth: {
    token: 'your_secure_token_here',
  },
  storage: [
    {
      name: 'default',
      path: '/var/opt/gitlab/git-data/repositories',
    },
  ]
}

# Tell Rails where to find Gitaly
gitlab_rails['repositories_storages'] = {
  'default' => { 'gitaly_address' => 'tcp://ip_address_here:8075' },
}

# Internal API URL (important for multi-server setups)
gitlab_rails['internal_api_url'] = 'http://ip_address_here'

Control groups

For information on control groups, see Cgroups.

Background repository optimization

The way data is stored in the object database of a Git repository can become inefficient over time, which slows down Git operations. You can schedule Gitaly to run a daily background task with a maximum duration to clean up these items and improve performance.

[!warning] Background repository optimization can place significant load on the host while running. Make sure to schedule this during off-peak hours and keep the duration short (for example, 30-60 minutes).

Configure background repository optimization in one of two ways:

Edit /etc/gitlab/gitlab.rb and add:

ruby

gitaly['configuration'] = {
  # ...
  daily_maintenance: {
    # ...
    start_hour: 4,
    start_minute: 30,
    duration: '30m',
    storages: ['default'],
  },
}

Edit /home/git/gitaly/config.toml and add:

toml

[daily_maintenance]
start_hour = 4
start_minute = 30
duration = '30m'
storages = ["default"]

Rotate Gitaly authentication token

Rotating credentials in a production environment often requires downtime, causes outages, or both.

However, you can rotate Gitaly credentials without a service interruption. Rotating a Gitaly authentication token involves:

Verifying authentication monitoring.
Enabling auth transitioning mode.
Updating Gitaly authentication tokens.
Ensuring there are no authentication failures.
Disabling auth transitioning mode.
Verifying authentication is enforced.

This procedure also works if you are running GitLab on a single server. In that case, the Gitaly server and the Gitaly client refer to the same machine.

Verify authentication monitoring

Before rotating a Gitaly authentication token, verify that you can monitor the authentication behavior of your GitLab installation using Prometheus.

You can then continue the rest of the procedure.

Enable auth transitioning mode

Temporarily disable Gitaly authentication on the Gitaly servers by putting them into auth transitioning mode as follows:

ruby

# in /etc/gitlab/gitlab.rb
gitaly['configuration'] = {
  # ...
  auth: {
    # ...
    transitioning: true,
  },
}

After you have made this change, your Prometheus query should return something like:

promql

{enforced="false",status="would be ok"}  4424.985419441742

Because enforced="false", it is safe to start rolling out the new token.

Update Gitaly authentication token

To update to a new Gitaly authentication token, on each Gitaly client and Gitaly server:

Update the configuration:
ruby
```
# in /etc/gitlab/gitlab.rb
gitaly['configuration'] = {
   # ...
   auth: {
      # ...
      token: '<new secret token>',
   },
}
```
If you are using token_file, update the contents of the referenced file with the new token. No configuration change is needed. The token file is read on startup.
Restart Gitaly:
shell
```
gitlab-ctl restart gitaly
```

If you run your Prometheus query while this change is being rolled out, you see non-zero values for the enforced="false",status="denied" counter.

Ensure there are no authentication failures

After the new token is set, and all services involved have been restarted, you will temporarily see a mix of:

status="would be ok".
status="denied".

After the new token is picked up by all Gitaly clients and Gitaly servers, the only non-zero rate should be enforced="false",status="would be ok".

Disable auth transitioning mode

To re-enable Gitaly authentication, disable auth transitioning mode. Update the configuration on your Gitaly servers as follows:

ruby

# in /etc/gitlab/gitlab.rb
gitaly['configuration'] = {
  # ...
  auth: {
    # ...
    transitioning: false,
  },
}

[!warning] Without completing this step, you have no Gitaly authentication.

Verify authentication is enforced

Refresh your Prometheus query. You should now see a similar result as you did at the start. For example:

promql

{enforced="true",status="ok"}  4424.985419441742

enforced="true" means that authentication is being enforced.

Pack-objects cache

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed

Gitaly, the service that provides storage for Git repositories, can be configured to cache a short rolling window of Git fetch responses. This can reduce server load when your server receives lots of CI fetch traffic.

The pack-objects cache wraps git pack-objects, an internal part of Git that gets invoked indirectly by using the PostUploadPack and SSHUploadPack Gitaly RPCs. Gitaly runs PostUploadPack when a user does a Git fetch by using HTTP, or SSHUploadPack when a user does a Git fetch by using SSH. When the cache is enabled, anything that uses PostUploadPack or SSHUploadPack can benefit from it. It is independent of and unaffected by:

The transport (HTTP or SSH).
Git protocol version (v0 or v2).
The type of fetch, such as full clones, incremental fetches, shallow clones, or partial clones.

The strength of this cache is its ability to deduplicate concurrent identical fetches. It:

Can benefit GitLab instances where your users run CI/CD pipelines with many concurrent jobs. There should be a noticeable reduction in server CPU utilization.
Does not benefit unique fetches at all. For example, if you run a spot check by cloning a repository to your local computer, you are unlikely to see a benefit from this cache because your fetch is probably unique.

The pack-objects cache is a local cache. It:

Stores its metadata in the memory of the Gitaly process it is enabled in.
Stores the actual Git data it is caching in files on local storage.

Using local files has the benefit that the operating system may automatically keep parts of the pack-objects cache files in RAM, making it faster.

Because the pack-objects cache can lead to a significant increase in disk write IO, it is off by default.

Configure the cache

These configuration settings are available for the pack-objects cache. Each setting is discussed in greater detail below.

Setting	Default	Description
`enabled`	`false`	Turns on the cache. When off, Gitaly runs a dedicated `git pack-objects` process for each request.
`dir`	`<PATH TO FIRST STORAGE>/+gitaly/PackObjectsCache`	Local directory where cache files get stored.
`max_age`	`5m` (5 minutes)	Cache entries older than this get evicted and removed from disk.
`min_occurrences`	1	Minimum times a key must occur before a cache entry is created.

In /etc/gitlab/gitlab.rb, set:

ruby

gitaly['configuration'] = {
  # ...
  pack_objects_cache: {
    enabled: true,
    # The default settings for "dir", "max_age" and "min_occurences" should be fine.
    # If you want to customize these, see details below.
  },
}

`enabled` defaults to `false`

The cache is disabled by default because in some cases, it can create an extreme increase in the number of bytes written to disk. On GitLab.com, we have verified that our repository storage disks can handle this extra workload, but we felt we cannot assume this is true everywhere.

Cache storage directory `dir`

The cache needs a directory to store its files in. This directory should be:

In a file system with enough space. If the cache file system runs out of space, all fetches start failing.
On a disk with enough IO bandwidth. If the cache disk runs out of IO bandwidth, all fetches, and probably the entire server, slows down.

[!warning] All existing data in the specified directory will be removed. Take care not to use a directory with existing data.

By default, the cache storage directory is set to a subdirectory of the first Gitaly storage defined in the configuration file.

Multiple Gitaly processes can use the same directory for cache storage. Each Gitaly process uses a unique random string as part of the cache filenames it creates. This means:

They do not collide.
They do not reuse another process's files.

While the default directory puts the cache files in the same file system as your repository data, this is not requirement. You can put the cache files on a different file system if that works better for your infrastructure.

The amount of IO bandwidth required from the disk depends on:

The size and shape of the repositories on your Gitaly server.
The kind of traffic your users generate.

You can use the gitaly_pack_objects_generated_bytes_total metric as a pessimistic estimate, pretending your cache hit ratio is 0%.

The amount of space required depends on:

The bytes per second that your users pull from the cache.
The size of the max_age cache eviction window.

If your users pull 100 MB/s and you use a 5 minute window, then on average you have 5*60*100 MB = 30 GB of data in your cache directory. This average is an expected average, not a guarantee. Peak size may exceed this average.

Cache eviction window `max_age`

The max_age configuration setting lets you control the chance of a cache hit and the average amount of storage used by cache files. Entries older than max_age get deleted from the disk.

Eviction does not interfere with ongoing requests. It is OK for max_age to be less than the time it takes to do a fetch over a slow connection because Unix filesystems do not truly delete a file until all processes that are reading the deleted file have closed it.

Minimum key occurrences `min_occurrences`

The min_occurrences setting controls how often an identical request must occur before we create a new cache entry. The default value is 1, meaning that unique requests do not get written into the cache.

If you:

Increase this number, your cache hit rate goes down and the cache uses less disk space.
Decrease this number, your cache hit rate goes up and the cache uses more disk space.

You should set min_occurrences to 1. On GitLab.com, going from 0 to 1 saved us 50% cache disk space while barely affecting the cache hit rate.

Observe the cache

Logs for pack-objects caching was changed in GitLab 16.0.

You can observe the cache using Prometheus metrics and log fields.

Prometheus metrics

Gitaly exports the following Prometheus metrics for monitoring the pack-objects cache:

Metric	Type	Description
`gitaly_pack_objects_served_bytes_total`	Counter	Total number of bytes of `git-pack-objects` data served to clients
`gitaly_pack_objects_cache_lookups_total`	Counter	Number of cache lookups, with a `result` label indicating `hit` or `miss`
`gitaly_pack_objects_generated_bytes_total`	Counter	Total number of bytes generated by running `git-pack-objects`

Example Prometheus queries:

Cache hit rate:

promql

sum(rate(gitaly_pack_objects_cache_lookups_total{result="hit"}[5m])) /
sum(rate(gitaly_pack_objects_cache_lookups_total[5m]))

Bytes served from cache per second:

promql

rate(gitaly_pack_objects_served_bytes_total[5m])

Bytes generated (cache misses) per second:

promql

rate(gitaly_pack_objects_generated_bytes_total[5m])

Cache efficiency (bytes served vs bytes generated):

promql

rate(gitaly_pack_objects_served_bytes_total[5m]) /
rate(gitaly_pack_objects_generated_bytes_total[5m])

Log fields

These logs are part of the gRPC logs and can be discovered when a call is executed.

Field	Description
`pack_objects_cache.hit`	Indicates whether the current pack-objects cache was hit (`true` or `false`)
`pack_objects_cache.key`	Cache key used for the pack-objects cache
`pack_objects_cache.generated_bytes`	Size (in bytes) of the new cache being written
`pack_objects_cache.served_bytes`	Size (in bytes) of the cache being served
`pack_objects.compression_statistics`	Statistics regarding pack-objects generation
`pack_objects.enumerate_objects_ms`	Total time (in ms) spent enumerating objects sent by clients
`pack_objects.prepare_pack_ms`	Total time (in ms) spent preparing the packfile before sending it back to the client
`pack_objects.write_pack_file_ms`	Total time (in ms) spent sending back the packfile to the client. Highly dependent on the client's internet connection
`pack_objects.written_object_count`	Total number of objects Gitaly sends back to the client

In the case of a:

Cache miss, Gitaly logs both a pack_objects_cache.generated_bytes and pack_objects_cache.served_bytes message. Gitaly also logs some more detailed statistics of pack-object generation.
Cache hit, Gitaly logs only a pack_objects_cache.served_bytes message.

Example:

json

{
  "bytes":26186490,
  "correlation_id":"01F1MY8JXC3FZN14JBG1H42G9F",
  "grpc.meta.deadline_type":"none",
  "grpc.method":"PackObjectsHook",
  "grpc.request.fullMethod":"/gitaly.HookService/PackObjectsHook",
  "grpc.request.glProjectPath":"root/gitlab-workhorse",
  "grpc.request.glRepository":"project-2",
  "grpc.request.repoPath":"@hashed/d4/73/d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35.git",
  "grpc.request.repoStorage":"default",
  "grpc.request.topLevelGroup":"@hashed",
  "grpc.service":"gitaly.HookService",
  "grpc.start_time":"2021-03-25T14:57:52.747Z",
  "level":"info",
  "msg":"finished unary call with code OK",
  "peer.address":"@",
  "pid":20961,
  "span.kind":"server",
  "system":"grpc",
  "time":"2021-03-25T14:57:53.543Z",
  "pack_objects.compression_statistics": "Total 145991 (delta 68), reused 6 (delta 2), pack-reused 145911",
  "pack_objects.enumerate_objects_ms": 170,
  "pack_objects.prepare_pack_ms": 7,
  "pack_objects.write_pack_file_ms": 786,
  "pack_objects.written_object_count": 145991,
  "pack_objects_cache.generated_bytes": 49533030,
  "pack_objects_cache.hit": "false",
  "pack_objects_cache.key": "123456789",
  "pack_objects_cache.served_bytes": 49533030,
  "peer.address": "127.0.0.1",
  "pid": 8813,
}

`cat-file` cache

A lot of Gitaly RPCs need to look up Git objects from repositories. Most of the time we use git cat-file --batch processes for that. For better performance, Gitaly can re-use these git cat-file processes across RPC calls. Previously used processes are kept around in a git cat-file cache. To control how much system resources this uses, we have a maximum number of cat-file processes that can go into the cache.

The default limit is 100 cat-files, which constitute a pair of git cat-file --batch and git cat-file --batch-check processes. If you see errors about "too many open files", or an inability to create new processes, you may want to lower this limit.

Ideally, the number should be large enough to handle standard traffic. If you raise the limit, you should measure the cache hit ratio before and after. If the hit ratio does not improve, the higher limit is probably not making a meaningful difference. Here is an example Prometheus query to see the hit rate:

plaintext

sum(rate(gitaly_catfile_cache_total{type="hit"}[5m])) / sum(rate(gitaly_catfile_cache_total{type=~"(hit)|(miss)"}[5m]))

Configure the cat-file cache in the Gitaly configuration file.

Configure commit signing for GitLab UI commits

Displaying Verified badge for signed GitLab UI commits introduced in GitLab 16.3 with a flag named gitaly_gpg_signing. Disabled by default.
Verifying the signatures using multiple keys specified in rotated_signing_keys option introduced in GitLab 16.3.
Enabled by default on GitLab Self-Managed and GitLab Dedicated in GitLab 17.0.

[!flag] On GitLab Self-Managed, by default this feature is available. To hide the feature, an administrator can disable the feature flag named gitaly_gpg_signing. On GitLab.com, this feature is not available. On GitLab Dedicated, this feature is available.

By default, Gitaly doesn't sign commits made using GitLab UI. For example, commits made using:

Web editor.
Web IDE.
Merge requests.

When you enable commit signing in Gitaly:

GitLab signs all commits made through the UI.
The signature verifies the committer's identity, not the author's identity.
You can configure Gitaly to reflect that a commit has been committed by your instance by setting committer_email and committer_name. For example, on GitLab.com these configuration options are set to [email protected] and GitLab.

rotated_signing_keys is a list of keys to use for verification only. Gitaly tries to verify a web commit using the configured signing_key, and then uses the rotated keys one by one until it succeeds. Set the rotated_signing_keys option when either:

The signing key is rotated.
You want to specify multiple keys to migrate projects from other instances and want to display their web commits as Verified.

Configure Gitaly to sign commits made with the GitLab UI in one of two ways:

Create a GPG key and export it, or create an SSH key. For optimal performance, use an EdDSA key.

Export GPG key:
shell
```
gpg --export-secret-keys <ID> > signing_key.gpg
```
Or create an SSH key (with no passphrase):
shell
```
ssh-keygen -t ed25519 -f signing_key.ssh
```
On the Gitaly nodes, copy the key into /etc/gitlab/gitaly/ and ensure the git user has permissions to read the file.

Edit /etc/gitlab/gitlab.rb and configure gitaly['git']['signing_key']:

ruby

gitaly['configuration'] = {
   # ...
   git: {
     # ...
     committer_name: 'Your Instance',
     committer_email: '[email protected]',
     signing_key: '/etc/gitlab/gitaly/signing_key.gpg',
     rotated_signing_keys: ['/etc/gitlab/gitaly/previous_signing_key.gpg'],
     # ...
   },
}

Save the file and reconfigure GitLab.

Create a GPG key and export it, or create an SSH key. For optimal performance, use an EdDSA key.

Export GPG key:
shell
```
gpg --export-secret-keys <ID> > signing_key.gpg
```
Or create an SSH key (with no passphrase):
shell
```
ssh-keygen -t ed25519 -f signing_key.ssh
```
On the Gitaly nodes, copy the key into /etc/gitlab.

Edit /home/git/gitaly/config.toml and configure signing_key:

toml

[git]
committer_name = "Your Instance"
committer_email = "[email protected]"
signing_key = "/etc/gitlab/gitaly/signing_key.gpg"
rotated_signing_keys = ["/etc/gitlab/gitaly/previous_signing_key.gpg"]

Save the file and restart GitLab.

Configure custom Git configuration

Gitaly does not read the system or user level Git configuration files. To provide custom Git configuration on the Gitaly server, use the git.config setting.

Edit /etc/gitlab/gitlab.rb:

ruby

gitaly['configuration'] = {
  # ...
  git: {
    # ...
    config: [
      { key: "fsck.badDate", value: "ignore" },
      ...
    ],
  },
}

Edit /home/git/gitaly/config.toml:

toml

[[git.config]]
key = "fsck.badDate"
value = "ignore"

Git configuration set by Gitaly

Gitaly sets the following Git configuration values, which cannot be overridden using the git.config setting:

advice.fetchShowForcedUpdates
attr.tree
bundle.heuristic
bundle.mode
bundle.version
core.alternateRefsCommand
core.autocrlf
core.bigFileThreshold
core.filesRefLockTimeout
core.fsync
core.fsyncMethod
core.hooksPath
core.packedRefsTimeout
core.useReplaceRefs
diff.noprefix
fetch.fsck.badTimezone
fetch.fsck.missingSpaceBeforeDate
fetch.fsck.zeroPaddedFilemode
fetch.fsckObjects
fetch.negotiationAlgorithm
fetch.recurseSubmodules
fetch.writeCommitGraph
fsck.badTimezone
fsck.missingSpaceBeforeDate
fsck.zeroPaddedFilemode
gc.auto
grep.threads
http.<url>.extraHeader
http.curloptResolve
http.extraHeader
http.followRedirects
init.defaultBranch
init.templateDir
maintenance.auto
pack.allowPackReuse
pack.island
pack.islandCore
pack.threads
pack.windowMemory
pack.writeBitmapLookupTable
pack.writeReverseIndex
receive.advertisePushOptions
receive.autogc
receive.fsck.badTimezone
receive.fsck.missingSpaceBeforeDate
receive.fsck.zeroPaddedFilemode
receive.hideRefs
receive.procReceiveRefs
remote.inmemory.fetch
remote.inmemory.url
remote.origin.fetch
remote.origin.url
repack.updateServerInfo
repack.writeBitmaps
transfer.bundleURI
transfer.fsckObjects
uploadpack.advertiseBundleURIs
uploadpack.allowAnySHA1InWant
uploadpack.allowFilter
uploadpack.hideRefs

Generate configuration using an external command

You can generate parts of the Gitaly configuration using an external command. You might do this:

To configure nodes without having to distribute the full configuration to each of them.
To configure using auto-discovery of the node's settings. For example, using DNS entries.
To configure secrets at startup of the node, so that don't need to be visible in plain text.

To generate configuration using an external command, you must provide a script that dumps the desired configuration of the Gitaly node in JSON format to its standard output.

For example, the following command configures the HTTP password used to connect to the GitLab internal API using an AWS secret:

ruby

#!/usr/bin/env ruby
require 'json'
JSON.generate({"gitlab": {"http_settings": {"password": `aws get-secret-value --secret-id ...`}}})

You must then make the script path known to Gitaly in one of two ways:

Edit /etc/gitlab/gitlab.rb and configure the config_command:

ruby

gitaly['configuration'] = {
    config_command: '/path/to/config_command',
}

Edit /home/git/gitaly/config.toml and configure config_command:

toml

config_command = "/path/to/config_command"

After configuration, Gitaly executes the command on startup and parses its standard output as JSON. The resulting configuration is then merged back into the other Gitaly configuration.

Gitaly fails to start up if either:

The configuration command fails.
The output produced by the command cannot be parsed as valid JSON.

Configure server-side backups

Introduced in GitLab 16.3.
Server-side support for restoring a specified backup instead of the latest backup introduced in GitLab 16.6.
Server-side support for creating incremental backups introduced in GitLab 16.6.
Server-side support added to Helm chart installations in GitLab 17.0.

Repository backups can be configured so that the Gitaly node that hosts each repository is responsible for creating the backup and streaming it to object storage. This helps reduce the network resources required to create and restore a backup.

Each Gitaly node must be configured to connect to object storage for backups.

After configuring server-side backups, you can create a server-side repository backup.

Configure Azure Blob storage

How you configure Azure Blob storage for backups depends on the type of installation you have. For self-compiled installations, you must set the AZURE_STORAGE_ACCOUNT and AZURE_STORAGE_KEY environment variables outside of GitLab.

Edit /etc/gitlab/gitlab.rb and configure the go_cloud_url:

ruby

gitaly['env'] = {
    'AZURE_STORAGE_ACCOUNT' => 'azure_storage_account',
    'AZURE_STORAGE_KEY' => 'azure_storage_key' # or 'AZURE_STORAGE_SAS_TOKEN'
}
gitaly['configuration'] = {
    backup: {
        go_cloud_url: 'azblob://<bucket>'
    }
}

For Helm-based deployments, see the server-side backup documentation for Gitaly chart.

Edit /home/git/gitaly/config.toml and configure go_cloud_url:

toml

[backup]
go_cloud_url = "azblob://<bucket>"

Configure Google Cloud storage

Google Cloud storage (GCP) authenticates using Application Default Credentials. Set up Application Default Credentials on each Gitaly server using either:

The gcloud auth application-default login command.
The GOOGLE_APPLICATION_CREDENTIALS environment variable. For self-compiled installations, set the environment variable outside of GitLab.

For more information, see Application Default Credentials.

The destination bucket is configured using the go_cloud_url option.

Edit /etc/gitlab/gitlab.rb and configure the go_cloud_url:

ruby

gitaly['env'] = {
    'GOOGLE_APPLICATION_CREDENTIALS' => '/path/to/service.json'
}
gitaly['configuration'] = {
    backup: {
        go_cloud_url: 'gs://<bucket>'
    }
}

For Helm-based deployments, see the server-side backup documentation for Gitaly chart.

Edit /home/git/gitaly/config.toml and configure go_cloud_url:

toml

[backup]
go_cloud_url = "gs://<bucket>"

Configure S3 storage

To configure S3 storage authentication:

If you authenticate with the AWS CLI, you can use the default AWS session.
Otherwise, you can use the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. For self-compiled installations, set the environment variables outside of GitLab.

For more information, see AWS Session documentation.

The destination bucket and region are configured using the go_cloud_url option.

Edit /etc/gitlab/gitlab.rb and configure the go_cloud_url:

ruby

gitaly['env'] = {
    'AWS_ACCESS_KEY_ID' => 'aws_access_key_id',
    'AWS_SECRET_ACCESS_KEY' => 'aws_secret_access_key'
}
gitaly['configuration'] = {
    backup: {
        go_cloud_url: 's3://<bucket>?region=us-west-1'
    }
}

For Helm-based deployments, see the server-side backup documentation for Gitaly chart.

Edit /home/git/gitaly/config.toml and configure go_cloud_url:

toml

[backup]
go_cloud_url = "s3://<bucket>?region=us-west-1"

Configure S3-compatible servers

S3-compatible servers are configured similarly to S3 with the addition of the endpoint parameter.

The following parameters are supported:

region: The AWS region.
endpoint: The endpoint URL.
disabledSSL: A value of true disables SSL.
s3ForcePathStyle: A value of true forces path-style addressing.

For Helm-based deployments, see the server-side backup documentation for Gitaly chart.

Edit /etc/gitlab/gitlab.rb and configure the go_cloud_url:

ruby

gitaly['env'] = {
    'AWS_ACCESS_KEY_ID' => '<your_access_key_id>',
    'AWS_SECRET_ACCESS_KEY' => '<your_secret_access_key>'
}
gitaly['configuration'] = {
    backup: {
        go_cloud_url: 's3://<bucket>?region=us-east-1&endpoint=s3.example.com:9000&disableSSL=true&s3ForcePathStyle=true'
    }
}

Edit /home/git/gitaly/config.toml and configure go_cloud_url:

toml

[backup]
go_cloud_url = "s3://<bucket>?region=us-east-1&endpoint=s3.example.com:9000&disableSSL=true&s3ForcePathStyle=true"

About the Gitaly token

Run Gitaly on its own server

Network architecture

Install Gitaly

Configure Gitaly servers

Configure authentication

Configure Gitaly server

Configure Gitaly clients

Mixed configuration

GitLab requires a default repository storage

Disable Gitaly where not required (optional)

Change the Gitaly listening interface

Control groups

Background repository optimization

Rotate Gitaly authentication token

Verify authentication monitoring

Enable auth transitioning mode

Update Gitaly authentication token

Ensure there are no authentication failures

Disable auth transitioning mode

Verify authentication is enforced

Pack-objects cache

Configure the cache

enabled defaults to false

Cache storage directory dir

Cache eviction window max_age

Minimum key occurrences min_occurrences

Observe the cache

Prometheus metrics

Log fields

cat-file cache

Configure commit signing for GitLab UI commits

Configure custom Git configuration

Git configuration set by Gitaly

Generate configuration using an external command

Configure server-side backups

Configure Azure Blob storage

Configure Google Cloud storage

Configure S3 storage

Configure S3-compatible servers

`enabled` defaults to `false`

Cache storage directory `dir`

Cache eviction window `max_age`

Minimum key occurrences `min_occurrences`

`cat-file` cache