Merge branch 'patch-28' into 'docs-darwinjs-update-ssh'

Exposing the existence of, concepts and configuration detail of Global Shared Deployment keys.

See merge request gitlab-org/gitlab-ce!17177

1 files changed, 43 insertions, 2 deletions

diff --git a/doc/ssh/README.md b/doc/ssh/README.md
index 33a2d7a88a7..51e5668e273 100644
--- a/doc/ssh/README.md
+++ b/doc/ssh/README.md
@@ -36,7 +36,7 @@ If you don't see the string or would like to generate a SSH key pair with a
 custom name continue onto the next step.
 
 >
-**Note:** Public SSH key may also be named as follows:
+NOTE: **Note:** Public SSH key may also be named as follows:
 - `id_dsa.pub`
 - `id_ecdsa.pub`
 - `id_ed25519.pub`
@@ -73,7 +73,7 @@ custom name continue onto the next step.
    key pair, but it is not required and you can skip creating a password by
    pressing enter.
 
-     >**Note:**
+     >NOTE: **Note:**
      If you want to change the password of your SSH key pair, you can use
      `ssh-keygen -p <keyname>`.
 
@@ -162,6 +162,8 @@ That's why it needs to uniquely map to a single user.
 
 ## Deploy keys
 
+### Per-repository deploy keys
+
 Deploy keys allow read-only or read-write (if enabled) access to one or
 multiple projects with a single SSH key pair.
 
@@ -185,6 +187,45 @@ a group.
 Deploy keys can be shared between projects, you just need to add them to each
 project.
 
+### Global shared deploy keys
+
+Global Shared Deploy keys allow read-only or read-write (if enabled) access to 
+be configured on any repository in the entire GitLab installation.
+
+This is really useful for integrating repositories to secured, shared Continuous
+Integration (CI) services or other shared services. 
+GitLab administrators can set up the Global Shared Deploy key in GitLab and 
+add the private key to any shared systems.  Individual repositories opt into
+exposing their repsitory using these keys when a project masters (or higher)
+authorizes a Global Shared Deploy key to be used with their project. 
+
+Global Shared Keys can provide greater security compared to Per-Project Deploy
+Keys since an administrator of the target integrated system is the only one
+who needs to know and configure the private key.
+
+GitLab administrators setup Global Deploy keys in the Admin area under the
+section **Deploy Keys**.  Ensure keys have a meaningful title as that will be
+the primary way for project masters and owners to identify the correct Global
+Deploy key to add.  For instance, if the key gives access to a SaaS CI instance,
+use the name of that service in the key name if that is all it is used for.
+When creating Global Shared Deploy keys, give some thought to the granularity
+of keys - they could be of very narrow usage such as just a specific service or 
+of broader usage for something like "Anywhere you need to give read access to 
+your repository".
+
+Once a GitLab administrator adds the Global Deployment key, project masters 
+and owners can add it in project's **Settings > Repository** section by expanding the 
+**Deploy Key** section and clicking **Enable** next to the appropriate key listed 
+under **Public deploy keys available to any project**.
+
+NOTE: **Note:** The heading 'Public deploy keys available to any project' only appears
+if there is at least one Global Deploy Key configured.
+
+NOTE: **Note:** Defining Global Deploy Keys does not expose any given repository via
+the key until that respository adds the Global Deploy Key to their project.
+In this way the Global Deploy Keys enable access by other systems, but do
+not implicitly give any access just by setting them up.
+
 ## Applications
 
 ### Eclipse