Add more sections in GPG docsdocs/gpg-refactor

1. Generating a GPG key
1. Signing commits
1. Associating a GPG key with Git

2 files changed, 173 insertions, 21 deletions

diff --git a/doc/user/project/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png b/doc/user/project/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png
index f715c46adc3..5c14df36d73 100644
--- a/doc/user/project/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png
+++ b/doc/user/project/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png
diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md
index d90bd46d003..3ea2203c895 100644
--- a/doc/user/project/gpg_signed_commits/index.md
+++ b/doc/user/project/gpg_signed_commits/index.md
@@ -7,7 +7,7 @@ All you need to do is upload the public GPG key in your profile settings.
 
 GPG verified tags are not supported yet.
 
-## Getting started
+## Getting started with GPG
 
 Here are a few guides to get you started with GPG:
 
@@ -28,7 +28,104 @@ to be met:
 1. The public key needs to be added your GitLab account
 1. One of the emails in the GPG key matches your **primary** email
 
-## Adding a GPG key
+## Generating a GPG key
+
+If you don't already have a GPG key, the following steps will help you get
+started:
+
+1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system
+1. Generate the private/public key pair with the following command:
+
+    ```sh
+    gpg --full-gen-key
+    ```
+
+    This will spawn a series of questions.
+
+1. The first question is which algorithm can be used.  Select the kind you want
+   or press <kbd>Enter</kbd> to choose the default (RSA and RSA):
+
+    ```
+    Please select what kind of key you want:
+       (1) RSA and RSA (default)
+       (2) DSA and Elgamal
+       (3) DSA (sign only)
+       (4) RSA (sign only)
+    Your selection? 1
+    ```
+
+1. The next question is key length. We recommend to choose the highest value
+   which is `4096`:
+
+    ```
+    RSA keys may be between 1024 and 4096 bits long.
+    What keysize do you want? (2048) 4096
+    Requested keysize is 4096 bits
+    ```
+1. Next, you need to specify the validity period of your key. This is something
+   subjective, and you can use the default value which is to never expire:
+
+    ```
+    Please specify how long the key should be valid.
+             0 = key does not expire
+          <n>  = key expires in n days
+          <n>w = key expires in n weeks
+          <n>m = key expires in n months
+          <n>y = key expires in n years
+    Key is valid for? (0) 0
+    Key does not expire at all
+    ```
+
+1. Confirm that the answers you gave were correct by typing `y`:
+
+    ```
+    Is this correct? (y/N) y
+    ```
+
+1. Enter you real name, the email address to be associated with this key (should
+   match the primary email address you use in GitLab) and an optional comment
+   (press <kbd>Enter</kbd> to skip):
+
+    ```
+    GnuPG needs to construct a user ID to identify your key.
+
+    Real name: Mr. Robot
+    Email address: mr@robot.sh
+    Comment:
+    You selected this USER-ID:
+        "Mr. Robot <mr@robot.sh>"
+
+    Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+    ```
+
+1. Pick a strong password when asked and type it twice to confirm.
+1. Use the following command to list the private GPG key you just created:
+
+    ```
+    gpg --list-secret-keys mr@robot.sh
+    ```
+
+    Replace `mr@robot.sh` with the email address you entered above.
+
+1. Copy the GPG key ID that starts with `sec`. In the following example, that's
+   `0x30F2B65B9246B6CA`:
+
+    ```
+    sec   rsa4096/0x30F2B65B9246B6CA 2017-08-18 [SC]
+          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
+    uid                   [ultimate] Mr. Robot <mr@robot.sh>
+    ssb   rsa4096/0xB7ABC0813E4028C0 2017-08-18 [E]
+    ```
+
+1. Export the public key of that ID (replace your key ID from the previous step):
+
+    ```
+    gpg --armor --export 0x30F2B65B9246B6CA
+    ```
+
+1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account)
+
+## Adding a GPG key to your account
 
 >**Note:**
 Once you add a key, you cannot edit it, only remove it. In case the paste
@@ -50,18 +147,74 @@ You can add a GPG key in your profile's settings:
 
     ![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
 
-## Removing a GPG key
+## Associating your GPG key with Git
 
-Removing a key **does not unverify** already signed commits. Commits that were
-verified by using this key will stay verified. Only unpushed commits will stay
-unverified once you remove this key. To unverify already signed commits, you need
-to [revoke the associated GPG key](#revoking-a-gpg-key) from your account.
+After you have [created your GPG key](#generating-a-gpg-key) and [added it to
+your account](#adding-a-gpg-key-to-your-account), it's time to tell Git which
+key to use.
 
-To remove a GPG key from your account:
+1. Use the following command to list the private GPG key you just created:
 
-1. On the upper right corner, click on your avatar and go to your **Settings**.
-1. Navigate to the **GPG keys** tab.
-1. Click on the trash icon besides the GPG key you want to delete.
+    ```
+    gpg --list-secret-keys mr@robot.sh
+    ```
+
+    Replace `mr@robot.sh` with the email address you entered above.
+
+1. Copy the GPG key ID that starts with `sec`. In the following example, that's
+   `0x30F2B65B9246B6CA`:
+
+    ```
+    sec   rsa4096/0x30F2B65B9246B6CA 2017-08-18 [SC]
+          D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
+    uid                   [ultimate] Mr. Robot <mr@robot.sh>
+    ssb   rsa4096/0xB7ABC0813E4028C0 2017-08-18 [E]
+    ```
+
+1. Tell Git to use that key to sign the commits:
+
+    ```
+    git config --global user.signingkey 0x30F2B65B9246B6CA
+    ```
+
+    Replace `0x30F2B65B9246B6CA` with your GPG key ID.
+
+## Signing commits
+
+After you have [created your GPG key](#generating-a-gpg-key) and [added it to
+your account](#adding-a-gpg-key-to-your-account), you can start signing your
+commits:
+
+1. Commit like you used to, the only difference is the addition of the `-S` flag:
+
+    ```
+    git commit -S -m "My commit msg"
+    ```
+
+1. Enter the passphrase of your GPG key when asked.
+1. Push to GitLab and check that your commits [are verified](#verifying-commits).
+
+If you don't want to type the `-S` flag every time you commit, you can tell Git
+to sign your commits automatically:
+
+```
+git config --global commit.gpgsign true
+```
+
+## Verifying commits
+
+1. Within a project or [merge request](../merge_requests/index.md), navigate to
+   the **Commits** tab. Signed commits will show a badge containing either
+   "Verified" or "Unverified", depending on the verification status of the GPG
+   signature.
+
+    ![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
+
+1. By clicking on the GPG badge, details of the signature are displayed.
+
+    ![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
+
+    ![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
 
 ## Revoking a GPG key
 
@@ -76,18 +229,17 @@ To revoke a GPG key:
 1. Navigate to the **GPG keys** tab.
 1. Click on **Revoke** besides the GPG key you want to delete.
 
-## Verifying commits
-
-1. Within a project navigate to the **Commits** tab. Signed commits will show a
-   badge containing either "Verified" or "Unverified", depending on the
-   verification status of the GPG signature.
-
-    ![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
+## Removing a GPG key
 
-1. By clicking on the GPG badge, details of the signature are displayed.
+Removing a key **does not unverify** already signed commits. Commits that were
+verified by using this key will stay verified. Only unpushed commits will stay
+unverified once you remove this key. To unverify already signed commits, you need
+to [revoke the associated GPG key](#revoking-a-gpg-key) from your account.
 
-    ![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
+To remove a GPG key from your account:
 
-    ![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
+1. On the upper right corner, click on your avatar and go to your **Settings**.
+1. Navigate to the **GPG keys** tab.
+1. Click on the trash icon besides the GPG key you want to delete.
 
 [ce-9546]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546