doc: Document supported ways to access Git installations

Document the different ways to access Git installations supported by
Gitaly. Most importantly, this also documents the way our new bundled
Git binaries work and why they were introduced.

1 files changed, 116 insertions, 0 deletions

diff --git a/doc/git-execution-environments.md b/doc/git-execution-environments.md
new file mode 100644
index 000000000..e4aacd608
--- /dev/null
+++ b/doc/git-execution-environments.md
@@ -0,0 +1,116 @@
+# Methods for Gitaly to access Git
+
+Because Git is at the heart of almost all interfaces provided by Gitaly, Gitaly
+must have access to Git. Gitaly supports three ways of accessing Git:
+
+- Bundled Git (recommended): Gitaly accesses bundled Git binaries. Unlike the
+  other two ways of accessing Git, this is not a complete Git installation but
+  only contains a subset of binaries that are required at runtime.
+- External Git distribution (not recommended): Gitaly accesses Git provided by
+  the operating system or manually installed by the administrator.
+- Gitaly Git distribution (not recommended): Gitaly accesses it's own version of
+  Git that may carry custom patches which are recommended, but not required.
+  These patches may fix known bugs or fix performance issues.
+
+The bundled Git execution environment is the recommended way to set up Gitaly.
+
+## Bundled Git (recommended)
+
+Instead of using a full Git distribution, you can use a bundled Git execution
+environment.
+
+To install bundled Git binaries, run `make install-bundled-git`. This Make
+target installs the bundled Git binaries in the `bin` directory of a location
+set with the `PREFIX` environment variable. For example:
+
+```shell
+make install-bundled-git PREFIX=/usr/local
+```
+
+Bundled Git binaries all have a `gitaly-` prefix so they do not clash with
+normal Git executables. Furthermore, bundled Git binaries may have a version
+suffix which allows Gitaly to install multiple different versions of Git at the
+same time. For example, `make install-bundled-git PREFIX=/usr/local` may install
+`gitaly-git-v2.35.1` and `gitaly-git-v2.36.0` into `/usr/local/bin`.
+
+Being able to install multiple Git versions in parallel solves two important
+issues:
+
+- When doing zero-downtime upgrades, a new Gitaly package can avoid replacing
+  Git binaries that are used by the currently running version of Gitaly. Gitaly
+  doesn't need to run in an intermediate state where the old version of Gitaly
+  is unexpectedly using newer Git binaries.
+- Gitaly can roll out new Git versions with the help of feature flags. This
+  means we can roll back to old versions of Git if a new version is exhibiting
+  faulty behavior.
+
+Git binaries expect to be able to locate helper binaries at runtime. However,
+because the bundled Git binaries all have a `gitaly-` prefix, the mechanisms Git
+has to locate those helpers don't work.
+
+To fix this, Gitaly has to bootstrap a Git execution environment on startup by:
+
+- Creating a temporary directory.
+- For each binary Git expects to exist, symlinking it into place.
+
+To tell Git where to find those symlinks, we run all Git commands with the
+`GIT_EXEC_PATH` environment variable that points into that temporary execution
+environment.
+
+Gitaly can be configured to use bundled binaries by setting the following keys:
+
+```toml
+# The binary directory where Gitaly's own binaries are installed. This directory
+# will also contain the bundled Git binaries.
+bin_dir = "/usr/local/bin"
+
+[git]
+use_bundled_binaries = true
+```
+
+## External Git Distribution
+
+You can run Gitaly with an external Git distribution that is not provided by
+Gitaly itself. For example:
+
+- Git distributions provided by the operating system's own package repositories.
+- A custom version of Git installed by the system administrator.
+
+To configure Gitaly to use an external Git distribution, point the Git binary
+path in its configuration file to the Git executable:
+
+```toml
+[git]
+bin_path = "/usr/bin/git"
+```
+
+If the binary path is not configured and Gitaly is not configured to use bundled
+binaries, Gitaly tries to resolve a Git executable automatically using the
+`PATH` variable. Relying on this behavior is not recommended and results in a
+warning on start up.
+
+External Git distributions must meet a minimum required version (for example,
+for [GitLab 13.11.0](https://docs.gitlab.com/ee/update/#13110)) which can change
+when upgrading Gitaly. Gitaly refuses to boot if the external Git distribution
+does not fulfill this version requirement.
+
+## Gitaly Git Distribution
+
+Gitaly provides its own version of Git that may contain a custom set of patches.
+These patches fix known issues we experience with Gitaly and may fix performance
+issues we have observed.
+
+While we backport patches that have been accepted in the upstream Git project,
+we do not plan to apply patches that will not eventually end up in Git itself.
+
+To use Gitaly's Git distribution, run `make git`. This Make target automatically
+fetches, builds, and installs Git into a specific directory that is configurable
+with the `GIT_PREFIX` environment variable. For example, to install the Git
+distribution into `/usr/local`:
+
+```shell
+make git GIT_PREFIX=/usr/local
+```
+
+Then configure the Git distribution the same way as an external Git
+distribution.