1 files changed, 69 insertions, 0 deletions
diff --git a/doc/administration/gitaly/configure_gitaly.md b/doc/administration/gitaly/configure_gitaly.md
index b31a02aae0a..a0c959d5de9 100644
--- a/doc/administration/gitaly/configure_gitaly.md
+++ b/doc/administration/gitaly/configure_gitaly.md
@@ -565,6 +565,12 @@ Note the following:
 - You can configure Gitaly servers with both an unencrypted listening address `listen_addr` and an
   encrypted listening address `tls_listen_addr` at the same time. This allows you to gradually
   transition from unencrypted to encrypted traffic if necessary.
+- When running Praefect sub-commands such as `dial-nodes` and `list-untracked-repositories` from the command line with Gitaly TLS enabled, you must set
+  the `SSL_CERT_DIR` or `SSL_CERT_FILE` environment variable so that the Gitaly certificate is trusted. For example: 
+
+   ```shell
+   sudo SSL_CERT_DIR=/etc/gitlab/trusted_certs /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes
+   ```
 
 To configure Gitaly with TLS:
 
@@ -1125,3 +1131,66 @@ Example:
   "time":"2021-03-25T14:57:53.543Z"
 }
 ```
+
+## Repository consistency checks
+
+Gitaly runs repository consistency checks:
+
+- When triggering a repository check.
+- When changes are fetched from a mirrored repository.
+- When users push changes into repository.
+
+These consistency checks verify that a repository has all required objects and
+that these objects are valid objects. They can be categorized as:
+
+- Basic checks that assert that a repository doesn't become corrupt. This
+  includes connectivity checks and checks that objects can be parsed.
+- Security checks that recognize objects that are suitable to exploit past
+  security-related bugs in Git.
+- Cosmetic checks that verify that all object metadata is valid. Older Git
+  versions and other Git implementations may have produced objects with invalid
+  metadata, but newer versions can interpret these malformed objects.
+
+Removing malformed objects that fail the consistency checks requires a
+rewrite of the repository's history, which often can't be done. Therefore,
+Gitaly by default disables consistency checks for a range of cosmetic issues
+that don't negatively impact repository consistency.
+
+By default, Gitaly doesn't disable basic or security-related checks so
+to not distribute objects that can trigger known vulnerabilities in Git
+clients. This also limits the ability to import repositories containing such
+objects even if the project doesn't have malicious intent.
+
+### Override repository consistency checks
+
+Instance administrators can override consistency checks if they must
+process repositories that do not pass consistency checks.
+
+For Omnibus GitLab installations, edit `/etc/gitlab/gitlab.rb` and set the
+following keys (in this example, to disable the `hasDotgit` consistency check):
+
+```ruby
+ignored_git_errors = ["hasDotgit = ignore"]
+omnibus_gitconfig['system'] = {
+        "fsck" => ignored_git_errors,
+        "fetch.fsck" => ignored_git_errors,
+        "receive.fsck" => ignored_git_errors,
+}
+```
+
+For source installs, edit the Gitaly configuration (`gitaly.toml`) to do the
+equivalent:
+
+```toml
+[[git.config]]
+key = "fsck.hasDotgit"
+value = "ignore"
+
+[[git.config]]
+key = "fetch.fsck.hasDotgit"
+value = "ignore"
+
+[[git.config]]
+key = "receive.fsck.hasDotgit"
+value = "ignore"
+```