Configuration

Gitaly uses a TOML configuration file to define its behavior. This guide covers all available configuration options.

Configuration File

The configuration file is typically located at:

Development: config.toml in your Gitaly directory
Production: /home/git/gitlab/tmp/sockets/private/gitaly/config.toml

An example configuration file is provided at config.toml.example in the Gitaly repository.

Core Settings

Socket Path

socket_path

string

required

Unix socket path for Gitaly to listen on.

socket_path = "/home/git/gitlab/tmp/sockets/private/gitaly.socket"

Binary Directory

bin_dir

string

required

The directory where Gitaly’s executables are stored.

bin_dir = "/home/git/gitaly/_build/bin"

Runtime Directory

runtime_dir

string

The directory where Gitaly can create all files required to properly operate at runtime. If not set, Gitaly will create a directory in the global temporary directory. This directory must exist.

runtime_dir = "/home/git/gitaly/run"

Network Configuration

TCP Listening

listen_addr

string

Listen on a TCP socket. Warning: This is insecure without TLS (no authentication).

listen_addr = "localhost:9999"

tls_listen_addr

string

Listen on a TCP socket with TLS encryption.

tls_listen_addr = "localhost:8888"

Prometheus Metrics

prometheus_listen_addr

string

Export metrics via Prometheus on this address.

prometheus_listen_addr = "localhost:9236"

Internal Sockets

internal_socket_dir

string

Configure where Gitaly creates sockets for internal connections. If unset, Gitaly creates a randomly named temp directory each time it boots. Non-Gitaly clients should never connect to these sockets.

internal_socket_dir = "/home/git/gitlab/tmp/sockets/private/internal"

Git Configuration

git

object

Git-specific settings.

[git]
bin_path = "/usr/bin/git"
catfile_cache_size = 100

git.bin_path

string

Path to the Git binary.

git.catfile_cache_size

integer

default:"100"

Number of cached git-cat-file processes.

Git Configuration Values

You can set Git configuration values that apply to all Git operations:

[[git.config]]
key = "fetch.fsckObjects"
value = "true"

Storage Configuration

See the Storage Configuration page for detailed information about configuring Git repository storage.

Logging Configuration

logging

object

Configure Gitaly’s logging behavior.

[logging]
dir = "/home/git/gitlab/log"
format = "json"
level = "info"

logging.dir

string

The directory where Gitaly stores extra log files.

logging.format

string

default:"text"

Output format for logs. Options: text or json.

logging.level

string

default:"info"

Log level to filter entries. One of: debug, info, warn, error, fatal, panic (in order of severity).

Sentry Integration

logging.sentry_dsn

string

Report exceptions from the Go server to Sentry.

sentry_dsn = "https://<key>:<secret>@sentry.io/<project>"

logging.ruby_sentry_dsn

string

Report exceptions from gitaly-ruby to Sentry.

ruby_sentry_dsn = "https://<key>:<secret>@sentry.io/<project>"

Prometheus Configuration

prometheus

object

Configure Prometheus metrics collection.

[prometheus]
grpc_latency_buckets = [0.001, 0.005, 0.025, 0.1, 0.5, 1.0, 10.0, 30.0, 60.0, 300.0, 1500.0]

prometheus.grpc_latency_buckets

array

Histogram buckets for recording GRPC method call latencies (in seconds).

Gitaly-Ruby Configuration

gitaly-ruby

object

Configuration for the Ruby helper process.

[gitaly-ruby]
dir = "/home/git/gitaly/ruby"
num_workers = 2
max_rss = 200000000
graceful_restart_timeout = "10m"
restart_delay = "5m"

gitaly-ruby.dir

string

required

The directory where gitaly-ruby is installed.

gitaly-ruby.num_workers

integer

default:"2"

Number of gitaly-ruby worker processes.

gitaly-ruby.max_rss

integer

default:"200000000"

Gitaly-ruby resident set size (RSS) that triggers a memory restart (in bytes).

gitaly-ruby.graceful_restart_timeout

duration

default:"10m"

Grace period before a gitaly-ruby process is forcibly terminated after exceeding max_rss.

gitaly-ruby.restart_delay

duration

default:"5m"

Time that gitaly-ruby memory must remain high before a restart.

gitaly-ruby.rugged_git_config_search_path

string

Search path for system gitconfig file (e.g., /etc, /opt/gitlab/embedded/etc). Only affects RPCs that use Rugged.

GitLab Shell Configuration

gitlab-shell

object

GitLab Shell integration settings.

[gitlab-shell]
dir = "/home/git/gitlab-shell"

gitlab-shell.dir

string

required

The directory where gitlab-shell is installed.

Hooks Configuration

hooks

object

Custom Git hooks configuration.

[hooks]
custom_hooks_dir = "/home/git/custom_hooks"

hooks.custom_hooks_dir

string

Directory containing custom Git hooks to be executed.

GitLab Integration

gitlab

object

GitLab Rails application integration settings.

[gitlab]
secret_file = "/home/git/gitlab-shell/.gitlab_shell_secret"
url = "http+unix://%2Fhome%2Fgit%2Fgitlab%2Ftmp%2Fsockets%2Fgitlab-workhorse.socket"
relative_url_root = '/'

gitlab.secret_file

string

required

Path to the shared secret file for authenticating with GitLab.

gitlab.url

string

required

URL of the GitLab Rails application.

gitlab.relative_url_root

string

Only needed if a UNIX socket is used in url and GitLab is configured to use a relative path (e.g., /gitlab).

GitLab HTTP Settings

gitlab.http-settings

object

HTTP client configuration for GitLab API requests.

[gitlab.http-settings]
read_timeout = 300
self_signed_cert = false

gitlab.http-settings.read_timeout

integer

default:"300"

HTTP read timeout in seconds.

gitlab.http-settings.user

string

HTTP basic auth username.

gitlab.http-settings.password

string

HTTP basic auth password.

gitlab.http-settings.ca_file

string

Path to CA certificate file.

gitlab.http-settings.ca_path

string

Path to CA certificates directory.

gitlab.http-settings.self_signed_cert

boolean

default:"false"

Allow self-signed certificates.

Concurrency Configuration

Control the concurrency of RPC endpoints:

[[concurrency]]
rpc = "/gitaly.RepositoryService/GarbageCollect"
max_per_repo = 1
max_queue_wait = "1m"
max_queue_size = 10

concurrency.rpc

string

The full RPC method name.

concurrency.max_per_repo

integer

Maximum number of concurrent calls per repository.

concurrency.max_queue_wait

duration

Maximum time a request can wait in the queue.

concurrency.max_queue_size

integer

Maximum number of requests that can be queued.

Rate Limiting

Configure rate limiting for specific RPCs:

[[rate_limiting]]
rpc = "/gitaly.SmartHTTPService/PostUploadPackWithSidechannel"
interval = "1m"
burst = 5

rate_limiting.rpc

string

The full RPC method name to rate limit.

rate_limiting.interval

duration

Time window for rate limiting.

rate_limiting.burst

integer

Maximum number of requests allowed in the interval.

Daily Maintenance

Schedule daily maintenance tasks to optimize repositories:

[daily_maintenance]
start_hour = 23
start_minute = 30
duration = "45m"
storages = ["default"]
disabled = false

daily_maintenance.start_hour

integer

Hour to start daily maintenance (0-23).

daily_maintenance.start_minute

integer

Minute to start daily maintenance (0-59).

daily_maintenance.duration

duration

How long maintenance window lasts.

daily_maintenance.storages

array

List of storage names to run maintenance on.

daily_maintenance.disabled

boolean

default:"false"

Disable daily maintenance.

Cgroups Configuration

Control resource usage with cgroups:

[cgroups]
count = 10
mountpoint = "/sys/fs/cgroup"
hierarchy_root = "gitaly"

[cgroups.memory]
enabled = true
limit = 1048576

[cgroups.cpu]
enabled = true
shares = 512

cgroups.count

integer

Number of cgroup partitions to create.

cgroups.mountpoint

string

default:"/sys/fs/cgroup"

Cgroup mount point.

cgroups.hierarchy_root

string

default:"gitaly"

Root hierarchy for Gitaly cgroups.

cgroups.memory.enabled

boolean

default:"false"

Enable memory limits.

cgroups.memory.limit

integer

Memory limit in bytes.

cgroups.cpu.enabled

boolean

default:"false"

Enable CPU limits.

cgroups.cpu.shares

integer

CPU shares (relative weight).

Complete Example

Here’s a complete example configuration file:

socket_path = "/home/git/gitlab/tmp/sockets/private/gitaly.socket"
bin_dir = "/home/git/gitaly/_build/bin"

[git]
bin_path = "/usr/bin/git"
catfile_cache_size = 100

[[storage]]
name = "default"
path = "/home/git/repositories"

[logging]
dir = "/home/git/gitlab/log"
format = "json"
level = "info"

[gitaly-ruby]
dir = "/home/git/gitaly/ruby"
num_workers = 2

[gitlab-shell]
dir = "/home/git/gitlab-shell"

[hooks]
custom_hooks_dir = "/home/git/custom_hooks"

[gitlab]
secret_file = "/home/git/gitlab-shell/.gitlab_shell_secret"
url = "http+unix://%2Fhome%2Fgit%2Fgitlab%2Ftmp%2Fsockets%2Fgitlab-workhorse.socket"

[gitlab.http-settings]
self_signed_cert = false

Official Documentation

Complete administration and reference guide in the GitLab documentation

Overview

Setup & Configuration

High Availability

Operations

Advanced Topics

Development

Configuration File

Core Settings

Socket Path

Binary Directory

Runtime Directory

Network Configuration

TCP Listening

Prometheus Metrics

Internal Sockets

Git Configuration

Git Configuration Values

Storage Configuration

Logging Configuration

Sentry Integration

Prometheus Configuration

Gitaly-Ruby Configuration

GitLab Shell Configuration

Hooks Configuration

GitLab Integration

GitLab HTTP Settings

Concurrency Configuration

Rate Limiting

Daily Maintenance

Cgroups Configuration

Complete Example

Further Reading

Official Documentation

Build docs developers (and LLMs) love

Overview

Setup & Configuration

High Availability

Operations

Advanced Topics

Development

​Configuration File

​Core Settings

​Socket Path

​Binary Directory

​Runtime Directory

​Network Configuration

​TCP Listening

​Prometheus Metrics

​Internal Sockets

​Git Configuration

​Git Configuration Values

​Storage Configuration

​Logging Configuration

​Sentry Integration

​Prometheus Configuration

​Gitaly-Ruby Configuration

​GitLab Shell Configuration

​Hooks Configuration

​GitLab Integration

​GitLab HTTP Settings

​Concurrency Configuration

​Rate Limiting

​Daily Maintenance

​Cgroups Configuration

​Complete Example

​Further Reading

Official Documentation

Build docs developers (and LLMs) love

Configuration File

Core Settings

Socket Path

Binary Directory

Runtime Directory

Network Configuration

TCP Listening

Prometheus Metrics

Internal Sockets

Git Configuration

Git Configuration Values

Storage Configuration

Logging Configuration

Sentry Integration

Prometheus Configuration

Gitaly-Ruby Configuration

GitLab Shell Configuration

Hooks Configuration

GitLab Integration

GitLab HTTP Settings

Concurrency Configuration

Rate Limiting

Daily Maintenance

Cgroups Configuration

Complete Example

Further Reading