Restored some fingerprint-related material and added suggested review changesdocs/refactor-repository-mirroring

1 files changed, 32 insertions, 12 deletions

diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md
index 576907af064..4225d1aa31d 100644
--- a/doc/workflow/repository_mirroring.md
+++ b/doc/workflow/repository_mirroring.md
@@ -59,8 +59,8 @@ mirror diverging. All changes will end up in the mirrored repository whenever:
 
 Changes pushed to files in the repository are automatically pushed to the remote mirror at least:
 
-- Once every five minutes after they are received.
-- Once every minute if **Only mirror protected branches** is enabled.
+- Within five minutes of being received.
+- Within one minute if **Only mirror protected branches** is enabled.
 
 In the case of a diverged branch, you will see an error indicated at the **Mirroring repositories**
 section.
@@ -171,6 +171,31 @@ If you click the:
 - **Detect host keys** button, GitLab will fetch the host keys from the server and display the fingerprints.
 - **Input host keys manually** button, a field is displayed where you can paste in host keys.
 
+You now need to verify that the fingerprints are those you expect. GitLab.com
+and other code hosting sites publish their fingerprints in the open for you
+to check:
+
+- [AWS CodeCommit](http://docs.aws.amazon.com/codecommit/latest/userguide/regions.html#regions-fingerprints)
+- [Bitbucket](https://confluence.atlassian.com/bitbucket/use-the-ssh-protocol-with-bitbucket-cloud-221449711.html#UsetheSSHprotocolwithBitbucketCloud-KnownhostorBitbucket%27spublickeyfingerprints)
+- [GitHub](https://help.github.com/articles/github-s-ssh-key-fingerprints/)
+- [GitLab.com](https://about.gitlab.com/gitlab-com/settings/#ssh-host-keys-fingerprints)
+- [Launchpad](https://help.launchpad.net/SSHFingerprints)
+- [Savannah](http://savannah.gnu.org/maintenance/SshAccess/)
+- [SourceForge](https://sourceforge.net/p/forge/documentation/SSH%20Key%20Fingerprints/)
+
+Other providers will vary. If you're running self-managed GitLab, or otherwise
+have access to the source server, you can securely gather the key fingerprints:
+
+```sh
+$ cat /etc/ssh/ssh_host*pub | ssh-keygen -E md5 -l -f -
+256 MD5:f4:28:9f:23:99:15:21:1b:bf:ed:1f:8e:a0:76:b2:9d root@example.com (ECDSA)
+256 MD5:e6:eb:45:8a:3c:59:35:5f:e9:5b:80:12:be:7e:22:73 root@example.com (ED25519)
+2048 MD5:3f:72:be:3d:62:03:5c:62:83:e8:6e:14:34:3a:85:1d root@example.com (RSA)
+```
+
+NOTE: **Note:**
+You may need to exclude `-E md5` for some older versions of SSH.
+
 When pulling changes from the source repository, GitLab will now check that at least one of the stored
 host keys matches before connecting. This can prevent malicious code from being injected into your
 mirror, or your password being stolen.
@@ -196,7 +221,7 @@ If you need to change the key at any time, you can click the **Regenerate key**
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4559) in
 > [GitLab Starter](https://about.gitlab.com/pricing/) 10.6.
 
-You can choose to always update your local branches with remote version versions, even if they have
+You can choose to always update your local branches with remote versions, even if they have
 diverged from the remote.
 
 CAUTION: **Caution:**
@@ -251,11 +276,10 @@ update button which is available on the **Mirroring repositories** section of th
 CAUTION: **Caution:**
 Bidirectional mirroring may cause conflicts.
 
-If you configure a repository to pull and push to a second remote, there is no guarantee that it
-will update correctly on both remotes.
-
-If you configure a repository for bidirectional mirroring, you should consider when conflicts occur
-who and how they will be resolved.
+If you configure a GitLab repository to both pull from, and push to, the same remote source, there
+is no guarantee that either repository will update correctly. If you set up a repository for
+bidirectional mirroring, you should prepare for the likely conflicts by deciding who will resolve
+them and how they will be resolved.
 
 Rewriting any mirrored commit on either remote will cause conflicts and mirroring to fail. This can
 be prevented by:
@@ -272,10 +296,6 @@ a [Push event webhook](../user/project/integrations/webhooks.md#push-events) to
 pull to GitLab. Push mirroring from GitLab is rate limited to once per minute when only push mirroring
 protected branches.
 
-It may be possible to implement a locking mechanism using the server-side `pre-receive` hook to prevent
-the race condition. For more information, read about [configuring custom Git hooks](../administration/custom_hooks.md)
-on the GitLab server.
-
 ### Preventing conflicts using a `pre-receive` hook
 
 > **Warning:** The solution proposed will negatively impact the performance of