Skip to main content

​
Introduction to Gitaly

Gitaly is a Git RPC service for handling all the git calls made by GitLab. It provides fault-tolerant horizontal scaling of Git storage in GitLab, particularly on gitlab.com.
Gitaly is already included in your GitLab installation. Most users won’t need to install Gitaly separately.

​
What is Gitaly?

Gitaly is a layer that brings horizontal scaling and higher availability to massively scaled Git operations through optimizations in:
  • Disk locality - Moving Git operations close to storage
  • Caching - Caching results of intensive operations like git pack-objects
  • Coordination - Managing operations between multiple nodes
  • Cluster synchronization - Keeping repositories in sync across nodes
  • Sharding - Distributing repositories across storage

​
Key Features

RPC-Based Architecture

Uses gRPC for high-performance remote procedure calls, exposing high-level Git operations instead of low-level lookups

Horizontal Scaling

Scales Git storage horizontally by eliminating NFS bottlenecks and moving Git operations close to disk

High Availability

Built-in HA solution with Praefect for asynchronous replication and automatic failover

Performance Optimization

Centralized monitoring, intelligent caching, and reduced filesystem latency for Git operations

​
Why Gitaly?

Git’s architectural characteristics make horizontal scaling challenging:
  • Stateful, ACID transactions - Database-like workload with memory/CPU/disk IO requirements
  • Process atomic transactions - One commit coordinated by one Git process
  • Storage channel speeds - Assumes low latency, high bandwidth storage access
  • Burst resource needs - High burst CPU, memory, and storage utilization based on content size
These characteristics make remote file systems (like NFS) unreliable for Git operations at scale. Gitaly solves this by:
  1. Providing one central place to monitor operations
  2. Implementing performance improvements through caching
  3. Moving Git operations from the app to the file/git server via RPC
  4. Enabling distributed storage and read operations
As of GitLab 11.5, almost all application code accesses Git repositories through Gitaly instead of direct disk access. GitLab.com production no longer uses NFS mounts for Git repositories.

​
Project Goals

Gitaly focuses on two main areas:
  1. Migrate from NFS to RPC - Replace repository access via NFS with gitaly-proto, GitLab’s Git RPC protocol
  2. Evolve infrastructure - Move from large Gitaly servers managed as “pets” to smaller servers that are “cattle”

​
Gitaly Clients

Several GitLab components act as Gitaly clients:
  • gitlab-rails - The main GitLab Rails application
  • gitlab-shell - For git clone, git push via SSH
  • gitlab-workhorse - For git clone via HTTPS and serving raw Git data
  • gitaly-ssh - For internal Git data transfers between Gitaly servers
  • gitaly-ruby - For RPCs that interact with multiple repositories

​
Get Started

Architecture Overview

Learn about Gitaly’s architecture, design decisions, and how it fits into GitLab

Quick Start

Get Gitaly up and running with configuration examples and setup instructions

Configuration Reference

Detailed configuration options for Gitaly and Praefect

High Availability

Set up Praefect for asynchronous replication and failover

​
Name Origin

Gitaly is a tribute to git and the town of Aly. Where the town of Aly has zero inhabitants most of the year, Gitaly aims to reduce the number of disk operations to zero for most actions. It also sounds like Italy, the capital of which is the destination of all roads - all git actions in GitLab end up in Gitaly.

Build docs developers (and LLMs) love

Get started for freeTalk to us