Gitaly Basics�Stan Hu - May 1, 2017

Goals

• This is a basic introduction on how Gitaly works with GitLab
• Only intended to jumpstart learning

​

Required Reading for Gitaly

• README.md in Gitaly repository
• Jacob Vosmaer’s presentation at Git Paris meetup

Why is git over NFS slow?

• Let’s start with finding all branch names on GitLab CE:

​

​

​

• strace -s 1024 ruby rug-test.rb >& out.txt

strace output

Read .git/packed-refs

Each line contains a SHA -> ref name

Verify each ref exists

Repeat 1619+ times

Total time over network

• Let’s assume 1 ms per round trip for NFS
• 1619 refs as of April 30, 2017
• Each requires at least one lstat() (possibly more calls)
• Time taken: > 1.6 s!
• That is an eternity

How we can do better

• Observation: git is fast on a local disk
• Gitaly’s simple idea:

​

Do git work locally

Return the results over the network

​

​

​

​

Unicorn (Rails)

Workhorse (Go)

​

​

gitaly (Go binary)�

git <command>

Testing out Gitaly in 9.1

In gitlab-rails console:

irb(main):01:0> proj = Project.find_by_full_path(GROUP/PROJECT)

irb(main):02:0> proj.repository.gitaly_ref_client.branch_names

=> ["bugfix.groovy-triple-quotes", "bugfix.javascript-colons-again", "bugfix.racket-stress-test", "feature.matlab", "feature.scala", "feature.vue", "hotfix.line-number-alignment", "master", "refactor.guessers", "refactor.split-html", "spike.inheritance","spike.token-perf"]

​

This example is not actually active in 9.1 yet �Will be simplified to repository.branch_names later

​

How does that work?

gitlab-org/gitlab-ce:lib/gitlab/gitaly_client/ref.rb

gitlab-org/gitlab-ce:lib/gitlab/git/repository.rb

Feature flag

gRPC crash course

• Gitaly: initially considered using a standard REST API
• gRPC has advantages
• Basic concepts
• Service: group of methods
• Messages: a structure of fields (Google Protocol Buffers)
• See http://www.grpc.io/docs/tutorials/basic/ruby.html

​

Finding all branches, gRPC edition

ref.proto

​

​

​

​

​

shared.proto

Protocol Buffers -> gRPC Code

.proto file

Ruby (gitaly gem)

​

commit_pb.rb

ref_pb.rb

...

Go bindings

​

commit.pb.go

ref.pb.go

...

Rails

Gitaly server

gRPC

Putting it all together

1. .proto files -> Ruby and Go code via protoc tool
2. The Ruby bindings are published in the gitaly gem
3. Gitaly server (Go) vendors gitaly-proto repository
4. Unicorn, Workhorse instantiate a gRPC client
5. Gitaly server handles git calls
1. Example: loading all branch names

How much is Gitaly being used?

• Gitaly is on by default in GitLab 9.0
• info/refs migrated in Workhorse
• Feature flags for Rails endpoints, mostly off right now
• See Order of Migration doc
• In CE/EE repos, don’t hesitate to run:

cd lib

git grep -i gitaly

or

git grep -i grpc

Questions?