Git designed for AI agents.
Configuring Gitaly
This document describes how to configure the Gitaly server application.
Gitaly is configured via a TOML configuration file. Where this TOML file is located and how you should edit it depend on how you installed GitLab. See: https://docs.gitlab.com/administration/gitaly/
The configuration file is passed as an argument to the gitaly
executable. This is usually done by either omnibus-gitlab or your init
script.
gitaly /path/to/config.toml
Format
socket_path = "/path/to/gitaly.sock"
listen_addr = ":8081"
bin_dir = "/path/to/gitaly-executables"
prometheus_listen_addr = ":9236"
[auth]
# transitioning = false
# token = "abc123def456......."
[[storage]]
path = "/path/to/storage/repositories"
name = "my_shard"
# Gitaly may serve from multiple storages
#[[storage]]
#name = "other_storage"
#path = "/path/to/other/repositories"
| Name | Type | Required | Notes |
|---|---|---|---|
socket_path |
string | see notes | A path which Gitaly should open a Unix socket. Required unless listen_addr is set |
listen_addr |
string | see notes | TCP address for Gitaly to listen on. Required unless socket_path is set |
runtime_dir |
string | no | Directory in which Gitaly creates a per-process directory for the files it needs at runtime, such as the sockets for internal Gitaly calls. Must exist if set. If not set, Gitaly creates a temporary directory instead |
bin_dir |
string | yes | Directory containing Gitaly's executables |
prometheus_listen_addr |
string | no | TCP listen address for Prometheus metrics. If not set, no Prometheus listener is started |
storage |
array | yes | An array of storage shards |
Authentication
Gitaly can be configured to reject requests that do not contain a specific bearer token in their headers. This is a security measure to be used when serving requests over TCP.
Authentication is disabled when the token setting in config.toml is absent or the empty string.
[auth]
# Non-empty token: this enables authentication.
token = "the secret token"
You can store the token in a file and reference it using token_file.
The file must have permissions 0600 or 0400 to ensure it is only readable by the owner.
The token and token_file options are mutually exclusive.
[auth]
# Read token from a file (must have 0600 or 0400 permissions)
token_file = "/path/to/token/file"
It is possible to temporarily disable authentication with the 'transitioning' setting. This allows you to monitor (see below) if all clients are authenticating correctly without causing a service outage for clients that are not configured correctly yet.
Warning: Remember to disable 'transitioning' when you are done changing your token settings.
[auth]
token = "the secret token"
transitioning = true
All authentication attempts are counted in Prometheus under
the gitaly_authentications_total metric.
Storage
GitLab repositories are grouped into 'storages'. These are directories
(e.g. /home/git/repositories) containing bare repositories managed
by GitLab, with names (e.g. default).
These names and paths are also defined in the gitlab.yml
configuration file of gitlab-foss (or gitlab). When you run Gitaly on
the same machine as gitlab-foss, which is the default and recommended
configuration, storage paths defined in Gitaly's config.toml must
match those in gitlab.yml.
| Name | Type | Required | Notes |
|---|---|---|---|
path |
string | yes | Path to storage shard |
name |
string | yes | Name of storage shard |
Git
The following values can be set in the [git] section of the configuration file:
| Name | Type | Required | Notes |
|---|---|---|---|
catfile_cache_size |
integer | no | Maximum number of cached cat-file processes (see below). Default 100. |
cat-file cache
A lot of Gitaly RPC's need to look up Git objects from repositories.
Most of the time we use git cat-file --batch processes for that. For
the sake of performance, Gitaly can re-use thse git cat-file processes
across RPC calls. Previously used processes are kept around in a "Git
cat-file cache". In order 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 "catfiles", which constitute a pair of
git cat-file --batch and git cat-file --batch-check processes. If
you are seeing errors complaining 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 normal (peak) 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:
sum(rate(gitaly_catfile_cache_total{type="hit"}[5m])) / sum(rate(gitaly_catfile_cache_total{type=~"(hit)|(miss)"}[5m]))
Logging
Example:
[logging]
level = "warn"
| Name | Type | Required | Notes |
|---|---|---|---|
format |
string | no | Log format: text or json. Default: text |
level |
string | no | Log level: debug, info, warn, error, fatal, or panic. Default: info |
sentry_dsn |
string | no | Sentry DSN for exception monitoring |
sentry_environment |
string | no | Sentry Environment for exception monitoring |
Environment variables
| Name | Default | Notes |
|---|---|---|
GITALY_LOG_REQUEST_METHOD_ALLOW_PATTERN |
Regular expression that controls which gRPC methods should be logged | |
GITALY_LOG_REQUEST_METHOD_DENY_PATTERN |
^/grpc.health.v1.Health/Check$ |
Regular expression that controls which gRPC methods should be filtered out |
Note that GITALY_LOG_REQUEST_METHOD_ALLOW_PATTERN takes precedence
over GITALY_LOG_REQUEST_METHOD_DENY_PATTERN. If a pattern matches in
allow pattern, then it will be logged, even if it also matches the deny
pattern. All error messages are logged unconditionally.
By default, health check gRPC messages are not logged. To enable them,
set GITALY_LOG_REQUEST_METHOD_ALLOW_PATTERN to ..
Validate Gitaly configuration
To validate Gitaly configuration, use gitaly configuration validate. For example:
gitaly configuration validate < gitaly.config.toml
For more information, run:
gitaly configuration validate --help