qeesung/gitaly

1. Overall shape

Gitaly is a Go-based Git RPC service. Its core responsibility is to translate GitLab requests into local Git operations on repository filesystems, rather than storing Git data itself.

2. Primary runtime processes

The repo builds multiple executables with distinct roles: gitaly is the main repository service, praefect is the HA/replication coordinator, and helper binaries such as gitaly-ssh, gitaly-hooks, gitaly-backup, gitaly-debug, and gitaly-lfs-smudge cover transport, hooks, backup, diagnostics, and LFS-related workflows.

3. Client-facing boundaries

External callers are GitLab components: Rails, Workhorse, and gitlab-shell talk to Gitaly over gRPC/RPC. SSH and HTTP Git traffic are handled by specialized service paths in the repo, but they ultimately route back into the same Git execution and repository logic.

4. API contract and service partitioning

The proto/ directory defines the RPC surface. Generated Go stubs under proto/go/gitalypb/ are used by service implementations under internal/gitaly/service/* and internal/praefect/service/*. This is the main contract boundary between clients and server logic.

5. Gitaly server core

The main server lives under internal/gitaly/ and internal/gitaly/service/. It exposes Git operations grouped by domain: repository management, commits, refs, diffs, blobs, object pools, hooks, smart HTTP, SSH, cleanup, operations, conflicts, and analysis. Each service is a separate boundary around a family of RPCs.

6. Git execution model

Gitaly’s internal Git layer (internal/git/) wraps native git commands, packfiles, pkt-line streams, object lookup, revisions, refs, quarantine handling, and repository metadata. The service layer depends on this package to perform the actual Git work on disk.

7. Repository and storage model

Repository data is filesystem-backed. Supporting packages in internal/gitaly/storage/, internal/gitaly/repoutil/, internal/git/localrepo/, and internal/git/objectpool/ manage repository paths, alternates, object pools, snapshots, locking, and metadata. This is the main persistence boundary: Git data lives on local storage, not in a database.

8. Background maintenance and integrity

Several packages handle housekeeping and optimization, such as commit-graph maintenance, object pruning, repository optimization, and cleanup of stale data. These are internal workflows that operate on repositories independently of request/response RPCs.

9. High availability via Praefect

Praefect is the HA layer between clients and Gitaly nodes. It routes requests, tracks repository assignment and replication state, and coordinates consistency across replicas. Its state is persisted in PostgreSQL through the internal/praefect/datastore/ layer and updated by reconciliation/replication components.

10. Praefect subsystems

Praefect is split into router, node management, replicator, reconciler, verifier, transaction handling, repository cleanup, and health-checking concerns. These packages form the control plane for deciding which Gitaly node serves a repository and how data is replicated or repaired.

11. Transactional and metadata coordination

Both Gitaly and Praefect have transaction-related subsystems. Gitaly’s storage manager and WAL/snapshot packages coordinate repository changes, while Praefect’s transaction manager and voting logic coordinate multi-node repository operations and cluster metadata changes.

12. Transport, middleware, and observability

gRPC is the primary network transport. Shared infrastructure under internal/grpc/, internal/log/, internal/tracing/, internal/prometheus/, and internal/structerr/ provides middleware, auth, request metadata, rate/concurrency limiting, tracing, metrics, and structured error mapping. These are cross-cutting layers around the services.

13. Auth and security boundaries

Authentication helpers exist in auth/, internal/gitaly/server/auth/, and internal/grpc/middleware/. The repo also contains signature verification, GPG/SSH signing, quarantine handling, and custom hook support, which are important because many Git actions need controlled execution and content validation.

14. Operational tooling and environments

The repository includes extensive support for benchmark/demo cluster creation, Terraform/Ansible provisioning, CI config, and test helpers. These are not part of the runtime architecture, but they show that deployment is expected across single-node Gitaly, Praefect-backed clusters, and local test harnesses.

15. What to draw in an architecture diagram

The main diagram should show GitLab clients calling either Gitaly directly or Praefect first; Gitaly then shells out to git and reads/writes repository files on local storage. For HA, Praefect sits in front of multiple Gitaly nodes and uses PostgreSQL for cluster state, routing, and replication coordination.