Quick Links: Roadmap | Want to Contribute? |
Gitaly is a Git RPC service for handling all the Git calls made by GitLab.
To see where it fits in please look at GitLab's architecture.
Fault-tolerant horizontal scaling of Git storage in GitLab, and particularly, on GitLab.com.
Almost all application code accesses Git repositories via Gitaly (with the exception of Rugged which we're working on removing).
Besides "Git over RPC" functionality, Gitaly also offers an optional high-availability solution.
We are building features according to our roadmap.
Most users won't install Gitaly on its own. It is already included in your GitLab installation.
Gitaly requires Go 1.20. Run make
to compile the executables
required by Gitaly.
Gitaly uses git
. Versions 2.41.0
and newer are supported.
The administration and reference guide is documented in the GitLab project.
See CONTRIBUTING.md and a list of quick win issues.
Gitaly is a tribute to Git and the town of Aly. Where the town of Aly has zero inhabitants most of the year we would like to reduce the number of disk operations to zero for most actions. It doesn't hurt that it sounds like Italy, the capital of which is the destination of all roads. All Git actions in GitLab end up in Gitaly.
High-level architecture overview:
graph LR
subgraph "Gitaly Service"
Gitaly == git ==> Filesystem
end
subgraph "Clients"
Rails[gitlab-rails] --> Gitaly
Workhorse --> Gitaly
Shell[gitlab-shell] -- command-line\nclient --> Gitaly
Gitaly -. Authorization .-> Rails
end
Rails -. Rugged .-> Filesystem
In High Availability mode, the current implementation looks like this (some details omitted):
graph LR
subgraph "Gitaly Nodes"
Gitaly == git ==> Filesystem
end
subgraph "Praefects"
LB[typical setup uses a loadbalancer] --> P1
LB --> P2
P1[Praefect 1]
P2[Praefect N]
P1 --> PG[(PostgreSQL)]
P2 --> PG
end
subgraph "Clients"
Rails[gitlab-rails]
Workhorse
Shell[gitlab-shell]
end
Clients --> Praefects --> Gitaly
As of Q4 2018, the following GitLab components act as Gitaly clients:
gitlab
: the main GitLab Rails application.gitlab-shell
: forgit clone
,git push
etc. via SSH.gitlab-workhorse
: forgit clone
via HTTPS and for slow requests that serve raw Git data.gitaly-ssh
: for internal Git data transfers between Gitaly servers.
The clients written in Go (gitlab-shell
, gitlab-workhorse
, gitaly-ssh
)
use library code from the
gitlab.com/gitlab-org/gitaly/client
package.
Gitaly offers a High Availability solution known as Gitaly Cluster (product documentation).
- In its current iteration, client traffic goes through Praefect, which then replicates data to multiple Gitaly servers, and stores state in a PostgreSQL database (see Design above).
- We are working on a new distributed replication solution referred to as Raft, notably removing the need for Praefect and its database, and offering stricter consistency guarantees. See this epic for details on the new design and its progress.
More about the project and its processes is detailed in the docs.
Gitaly supports distributed tracing through LabKit using OpenTracing APIs.
By default, no tracing implementation is linked into the binary, but different OpenTracing providers can be linked in using build tags/build constraints. This can be done by setting the BUILD_TAGS
make variable.
For more details of the supported providers, see LabKit, but as an example, for Jaeger tracing support, include the tags: BUILD_TAGS="tracer_static tracer_static_jaeger"
.
make BUILD_TAGS="tracer_static tracer_static_jaeger"
Once Gitaly is compiled with an opentracing provider, the tracing configuration is configured via the GITLAB_TRACING
environment variable.
For example, to configure Jaeger, you could use the following command:
GITLAB_TRACING=opentracing://jaeger ./gitaly config.toml
Gitaly supports Continuous Profiling through LabKit using Stackdriver Profiler.
For more information on how to set it up, see the LabKit monitoring docs.
-
A walkthrough of the Praefect codebase.
-
How to configure backpressure in Gitaly
An overview of the knobs in the Gitaly config to set limits on incoming traffic. There is also written documentation.
-
How Gitaly fits into GitLab (Youtube) - a series of 1-hour training videos for contributors new to GitLab and Gitaly.
-
Part 1: the Gitaly client in
gitlab-ce
, 2019-02-21Overview of GitLab backend processes, GitLab Rails deep dive: Gitaly config in GitLab Rails, SQL data model, overview of how Gitaly calls get made via GitalyClient.call.
-
What is in a
gitaly-proto
Repository message, legacy vs hashed storage (repository directories),git clone
via SSH,gitlab-shell
,authorized_keys
and forced commands, what happens duringgit push
. -
A closer look at the final stage of
git push
where the Git hooks run and the refs get updated. Interaction between the Git hooks and GitLab internal API. The Git object quarantine mechanism. Preview of Git HTTP (to be discussed next time). -
Intercepting Git HTTP traffic with mitmproxy, overview of Git HTTP clone steps, code walk in
gitlab-workhorse
andgitlab-ce
, investigating internal workhorse API messages used for Git HTTP. -
Part 5: Merge Requests across Forks, 2019-03-21
Fixing a locally broken Ruby gem C extension by recompiling, demo of how creating a MR across forks causes new commits to suddenly appear in the fork parent repository, deep dive into the FetchSourceBranch RPC, adding debug code to see how address and authentication metadata is passed down to
gitaly-ruby
, failed attempt to loggitaly-ssh
arguments, comparison ofgitaly-ssh
andgitlab-shell
, a Gitaly server can end up making RPC calls to itself. -
Part 6: Creating Git commits on behalf of Git users, 2019-03-21
Demonstrate how usually Git hooks are run by
git-receive-pack
, but sometimes bygitaly-ruby
. Deep dive into UserCommitFiles: where do those hooks actually get run? A look at UserMerge. How does Gitaly make merge commits. A look at the implementation of the special feature where users are not allowed push to a branch, but are allowed to merge into it. -
Part 7: How Gitaly uses Prometheus monitoring, 2019-07-09
What is Prometheus. Reconstructing a Grafana dashboard panel with PromQL. Adding a new counter to Gitaly. Querying Prometheus in Gitaly during development. Comparing latency calculation with ELK. GRPC Prometheus middleware in Gitaly.
-
-
TheConf talk on Scaling GitLab Git storage with Gitaly, 2019-08-16
-
Git Paris meetup, 2017-02-22 a high-level overview of what our plans are and where we are.