Skip to main content

​
Quick Start Guide

This guide will help you get Gitaly up and running for development or testing purposes.
Most users won’t install Gitaly separately - it’s already included in your GitLab installation.

​
Prerequisites

​
System Requirements

  • Go: Version 1.16 or 1.17
  • Ruby: Version 2.7
  • Git: Version 2.33.0 or newer
  • Make: For building the project

​
Optional Requirements

  • PostgreSQL: 9.6+ (required for Praefect high availability)
  • Docker: For running test databases

​
Installation

1

Clone the Repository

If you’re working with the GitLab Development Kit (GDK), Gitaly is already cloned at /path/to/gdk/gitaly.For standalone installation:
git clone https://gitlab.com/gitlab-org/gitaly.git
cd gitaly
2

Build Gitaly

Run make to download and compile Ruby dependencies, and compile the Gitaly Go executable:
make
This installs Gitaly into the ./_build/bin directory.
To build with distributed tracing support: make BUILD_TAGS="tracer_static tracer_static_jaeger"
3

Create Configuration File

Copy the example configuration file and customize it for your environment:
cp config.toml.example config.toml

​
Configuration

​
Basic Configuration

Edit your config.toml file with the minimum required settings: 
# Socket path for Gitaly to listen on
socket_path = "/home/git/gitlab/tmp/sockets/private/gitaly.socket"

# Directory where Gitaly's executables are stored
bin_dir = "/home/git/gitaly/_build/bin"

# Configure at least one storage
[[storage]]
name = "default"
path = "/home/git/repositories"
The storage path must point to a directory where Git repositories will be stored. This directory must exist and be writable by the Gitaly process.

​
Advanced Configuration Options

​
Authentication

Enable token-based authentication: 
[auth]
token = 'abc123secret'
transitioning = false  # Set to true to temporarily allow unauthenticated requests

​
Network Listeners

Configure TCP and TLS listeners: 
# Listen on TCP (insecure - no authentication)
listen_addr = "localhost:9999"

# Listen on TLS
tls_listen_addr = "localhost:8888"

[tls]
certificate_path = '/home/git/cert.cert'
key_path = '/home/git/key.pem'

​
Prometheus Metrics

Export metrics for monitoring: 
prometheus_listen_addr = "localhost:9236"

[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]

​
Git Configuration

Customize Git binary location and settings: 
[git]
bin_path = "/usr/bin/git"
catfile_cache_size = 100

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

​
Logging

Configure logging output: 
[logging]
dir = "/home/git/gitlab/log"
format = "json"
level = "info"  # One of: debug, info, warn, error, fatal, panic

# Optional: Report exceptions to Sentry
sentry_dsn = "https://<key>:<secret>@sentry.io/<project>"
ruby_sentry_dsn = "https://<key>:<secret>@sentry.io/<project>"

​
Gitaly-Ruby Configuration

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

​
Concurrency Control

Limit concurrent operations per RPC: 
[[concurrency]]
rpc = "/gitaly.RepositoryService/GarbageCollect"
max_per_repo = 1
max_queue_wait = "1m"
max_queue_size = 10

​
Rate Limiting

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

​
Daily Maintenance

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

​
Multiple Storages

Configure multiple storage locations: 
[[storage]]
name = "default"
path = "/home/git/repositories"

[[storage]]
name = "other_storage"
path = "/mnt/other_storage/repositories"

​
Running Gitaly

​
Start Gitaly

Run Gitaly with your configuration file: 
./gitaly config.toml

​
With Distributed Tracing

If compiled with tracing support: 
GITLAB_TRACING=opentracing://jaeger ./gitaly config.toml

​
In GitLab Development Kit

If using GDK, restart Gitaly after making changes: 
cd /path/to/gdk
make gitaly-setup
gdk restart gitaly
To prevent GDK from overwriting your Gitaly checkout, add to /path/to/gdk/gdk.yml:
gitaly:
  auto_update: false

​
Testing Your Installation

​
Verify Gitaly is Running

Check that Gitaly is listening on the configured socket: 
ls -l /home/git/gitlab/tmp/sockets/private/gitaly.socket

​
Check Logs

Monitor Gitaly logs for errors: 
tail -f /home/git/gitlab/log/gitaly.log

​
Test with GitLab

If integrated with GitLab, test Git operations: 
# Clone a repository via HTTP
git clone http://localhost:3000/root/test-project.git

# Clone via SSH
git clone git@localhost:root/test-project.git

​
Development Workflow

​
Building and Testing

1

Build the Project

make build
2

Prepare Test Repositories

make prepare-tests
3

Run Tests

For Praefect tests, start a PostgreSQL database:
docker rm -f $(docker ps -q --all -f name=praefect-pg) > /dev/null 2>&1
docker run --name praefect-pg -p 5432:5432 \
  -e POSTGRES_HOST_AUTH_METHOD=trust -d postgres:12.6
Run the full test suite:
make test
Run specific tests:
TEST_PACKAGES=./internal/gitaly/service/repository \
TEST_OPTIONS="-count=1 -run=TestRepositoryExists" \
make test-go
4

Clean Build Artifacts

make clean

​
Makefile Targets

Common make targets:
  • make build - Build Gitaly without installing
  • make install - Build and install Gitaly (modify PREFIX to change destination)
  • make test - Execute both Go and Ruby tests
  • make proto - Generate server and client code from protocol definitions
  • make clean - Remove all generated build artifacts

​
Configuration Persistence

Create a config.mak file next to the Makefile to persist build variables: 
# config.mak
V=1  # Verbose build
PROTOC_VERSION=3.17.3
BUILD_TAGS=tracer_static tracer_static_jaeger

​
Next Steps

Architecture

Learn about Gitaly’s design and architecture decisions

Configuration Reference

Explore all configuration options in detail

High Availability

Set up Praefect for HA and replication

Contributing

Learn how to contribute to Gitaly development

​
Troubleshooting

​
Common Issues

Gitaly fails to start
  • Check that the socket directory exists and is writable
  • Verify Git binary is in the configured bin_path
  • Check logs for specific error messages
Connection refused errors
  • Verify Gitaly is running: ps aux | grep gitaly
  • Check the socket path matches GitLab’s configuration
  • Ensure file permissions allow GitLab to access the socket
High memory usage
  • Review gitaly-ruby worker count and memory limits
  • Check for memory-intensive operations in logs
  • Consider adjusting max_rss and restart thresholds

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us