Clean up CI ssh keys docs [ci skip]

1 files changed, 81 insertions, 86 deletions

diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md
index 515194e5f5e..210f9c3e849 100644
--- a/doc/ci/ssh_keys/README.md
+++ b/doc/ci/ssh_keys/README.md
@@ -1,114 +1,109 @@
 # Using SSH keys
 
-GitLab currently doesn't have built-in support for SSH keys in build environment.
+GitLab currently doesn't have built-in support for managing SSH keys in a build
+environment.
 
 The SSH keys can be useful when:
-1. You want to checkout internal submodules,
-2. You want to download private packages using your package manager (ie. bundler),
-3. You want to deploy your app (ex. to Heroku or own server),
-4. You want to execute ssh commands from build environment on remote server,
-5. You want to rsync files from your build to remote server.
 
-If anyone of the above holds true, then you most likely need SSH key.
+1. You want to checkout internal submodules
+2. You want to download private packages using your package manager (eg. bundler)
+3. You want to deploy your application to eg. Heroku or your own server
+4. You want to execute SSH commands from the build server to the remote server
+5. You want to rsync files from your build server to the remote server
 
-There are two possibilities to add SSH keys to build environment.
+If anything of the above rings a bell, then you most likely need an SSH key.
 
-## Inject keys in your build environment
-The most widely supported is to inject SSH key into your build environment by extending your .gitlab-ci.yml.
-This is the universal solution which works with any type of executor (docker, shell, etc.).
+## Inject keys in your build server
 
-### How it works?
-1. We create a new SSH private key with [ssh-keygen](http://linux.die.net/man/1/ssh-keygen).
-2. We add the private key as the Secure Variable to project.
-3. We run the [ssh-agent](http://linux.die.net/man/1/ssh-agent) during build to load the private key.
+The most widely supported method is to inject an SSH key into your build
+environment by extending your `.gitlab-ci.yml`.
 
-The example [.gitlab-ci.yml](https://gitlab.com/gitlab-examples/ssh-private-key/blob/master/.gitlab-ci.yml) looks like this.
+This is the universal solution which works with any type of executor
+(docker, shell, etc.).
 
-### Make it work?
-1. First, go to terminal and generate a new SSH key:
-```bash
-$ ssh-keygen -t rsa -f my_key
-
-Generating public/private rsa key pair.
-Enter passphrase (empty for no passphrase): 
-Enter same passphrase again: 
-Your identification has been saved in my_key.
-Your public key has been saved in my_key.pub.
-The key fingerprint is:
-SHA256:tBJEfyJUGTMNmPCiPg4UHywHs67MxlM2iEBAlI/W+TY fingeprint
-The key's randomart image is:
-+---[RSA 2048]----+
-|=*. .o++*=       |
-|..=  +o..o.      |
-|.+++o + + .      |
-|+o*=.. + +       |
-|o+.=. . S        |
-|*.o .E .         |
-|o*o . .          |
-|.o..             |
-|  .              |
-+----[SHA256]-----+
-```
+### How it works
+
+1. Create a new SSH key pair with [ssh-keygen][]
+2. Add the private key as a **Secret Variable** to the project
+3. Run the [ssh-agent][] during build to load the private key.
+
+## SSH keys when using the Docker executor
 
-2. Create a new **Secure Variable** in your project settings on GitLab and name it: `SSH_PRIVATE_KEY`.
+You will first need to create an SSH key pair. For more information, follow the
+instructions to [generate an SSH key](../ssh/README.md).
 
-3. Copy the content of `my_key` and paste it as a **Value** of **SSH_PRIVATE_KEY**.
+Then, create a new **Secret Variable** in your project settings on GitLab
+following **Settings > Variables**. As **Key** add the name `SSH_PRIVATE_KEY`
+and in the **Value** field paste the content of your _private_ key that you
+created earlier.
+
+Next you need to modify your `.gitlab-ci.yml` with a `before_script` action.
+Add it to the top:
 
-4. Next you need to modify your `.gitlab-ci.yml` and at the top of the file add:
 ```
 before_script:
-# install ssh-agent (it is required for Docker, change apt-get to yum if you use CentOS-based image)
-- 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
+  # Install ssh-agent if not already installed, it is required by Docker.
+  # (change apt-get to yum if you use a CentOS-based image)
+  - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )'
+
+  # Run ssh-agent (inside the build environment)
+  - eval $(ssh-agent -s)
+
+  # Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
+  - ssh-add <(echo "$SSH_PRIVATE_KEY")
+
+  # For Docker builds disable host key checking. Be aware that by adding that
+  # you are suspectible to man-in-the-middle attacks.
+  # WARNING: Use this only with the Docker executor, if you use it with shell
+  # you will overwrite your user's SSH config.
+  - mkdir -p ~/.ssh
+  - '[[ -f /.dockerinit ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config`
+```
 
-# run ssh-agent (in build environment)
-- eval $(ssh-agent -s)
+As a final step, add the _public_ key from the one you created earlier to the
+services that you want to have an access to from within the build environment.
+If you are accessing a private GitLab repository you need to add it as a
+[deploy key](../ssh/README.md#deploy-keys).
 
-# add ssh key stored in SSH_PRIVATE_KEY variable to the agent store
-- ssh-add <(echo "$SSH_PRIVATE_KEY")
+That's it! You can now have access to private servers or repositories in your
+build environment.
 
-# for Docker builds disable host key checking, by adding that you are suspectible to man-in-the-middle attack
-- mkdir -p ~/.ssh
-- '[[ -f /.dockerinit ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config`
-```
+## SSH keys when using the Shell executor
 
-5. Add the public key from `my_key.pub` to services that you want to have an access from build.
+If you are using the Shell executor and not Docker, it is easier to set up an
+SSH key.
 
-6. If your builds are run using `shell` executor, you may need to login to server and execute the `ssh <address-of-my-server>` to store the fingerprint of remote server.
+You can generate the SSH key from the machine that GitLab Runner is installed
+on, and use that key for all projects that are run on this machine.
 
-## SSH keys when using Shell executor
-If use `shell`, not `docker` it can be easier to have the SSH key.
+First, you need to login to the server that runs your builds.
 
-We can generate the SSH key for the machine that holds `gitlab-runner` and use that key for all projects that are run on this machine.
+Then from the terminal login as the `gitlab-runner` user and generate the SSH
+key pair as described in the [SSH keys documentation](../ssh/README.md).
 
-1. First, login to server that runs your builds.
+As a final step, add the _public_ key from the one you created earlier to the
+services that you want to have an access to from within the build environment.
+If you are accessing a private GitLab repository you need to add it as a
+[deploy key](../ssh/README.md#deploy-keys).
+
+Once done, try to login to the remote server in order to accept the fingerprint:
 
-2. From terminal login as `gitlab-runner` user and generate the SSH private key:
 ```bash
-$ ssh-keygen -t rsa
-Generating public/private rsa key pair.
-Enter passphrase (empty for no passphrase): 
-Enter same passphrase again: 
-Your identification has been saved in ~/.ssh/id_rsa.
-Your public key has been saved in ~/.ssh/id_rsa.pub.
-The key fingerprint is:
-SHA256:tBJEfyJUGTMNmPCiPg4UHywHs67MxlM2iEBAlI/W+TY fingeprint
-The key's randomart image is:
-+---[RSA 2048]----+
-|=*. .o++*=       |
-|..=  +o..o.      |
-|.+++o + + .      |
-|+o*=.. + +       |
-|o+.=. . S        |
-|*.o .E .         |
-|o*o . .          |
-|.o..             |
-|  .              |
-+----[SHA256]-----+
+ssh <address-of-my-server>
 ```
 
-3. Add the public key from `~/.ssh/id_rsa.pub` to services that you want to have an access from build.
+For accessing repositories on GitLab.com, the `<address-of-my-server>` would be
+`git@gitlab.com`.
 
-4. Try to login for the first time and accept fingerprint:
-```bash
-ssh <address-of-my-server
-```
+## Example project
+
+We have set up an [Example SSH Project][ssh-example-repo] for your convenience
+that runs on [GitLab.com](https://gitlab.com) using our publicly available
+[shared runners](../runners/README.md).
+
+Want to hack on it? Simply fork it, commit and push your changes. Within a few
+moments the changes will be picked by a public runner and the build will begin.
+
+[ssh-keygen]: http://linux.die.net/man/1/ssh-keygen
+[ssh-agent]: http://linux.die.net/man/1/ssh-agent
+[ssh-example-repo]: https://gitlab.com/gitlab-examples/ssh-private-key/