doc: Document supported ways to access Git installationspks-doc-git-execution-environments

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..52c7bee4d
--- /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.