Clean up the GPG docs and mention push rulesdocs/gpg-mention-push-rules

1 files changed, 33 insertions, 29 deletions

diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md
index c6239c8e41c..c7e20f01a75 100644
--- a/doc/user/project/repository/gpg_signed_commits/index.md
+++ b/doc/user/project/repository/gpg_signed_commits/index.md
@@ -4,7 +4,7 @@ NOTE: **Note:**
 The term GPG is used for all OpenPGP/PGP/GPG related material and
 implementations.
 
-> - [Introduced][ce-9546] in GitLab 9.5.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546) in GitLab 9.5.
 > - Subkeys support was added in GitLab 10.1.
 
 GitLab can show whether a commit is verified or not when signed with a GPG key.
@@ -36,30 +36,22 @@ to be met:
 
 ## Generating a GPG key
 
-> **Notes:**
-> - If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in
->   the following commands.
-> - If Git is using `gpg` and you get errors like `secret key not available` or
->   `gpg: signing failed: secret key not available`, run the following command to
->   change to `gpg2`:
->
->     ```
->     git config --global gpg.program gpg2
->    ```
-
 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:
+1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system.
+   If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in
+   the following commands.
+1. Generate the private/public key pair with the following command, which will
+   spawn a series of questions:
 
     ```sh
     gpg --full-gen-key
     ```
-    
-    _NOTE: In some cases like Gpg4win on Windows and other Mac OS versions the command here may be ` gpg --gen-key`_
 
-    This will spawn a series of questions.
+    NOTE: **Note:**
+    In some cases like Gpg4win on Windows and other macOS versions, the command
+    here may be `gpg --gen-key`.
 
 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):
@@ -109,10 +101,10 @@ started:
     GnuPG needs to construct a user ID to identify your key.
 
     Real name: Mr. Robot
-    Email address: mr@robot.sh
+    Email address: <your_email>
     Comment:
     You selected this USER-ID:
-        "Mr. Robot <mr@robot.sh>"
+        "Mr. Robot <your_email>"
 
     Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
     ```
@@ -121,10 +113,10 @@ started:
 1. Use the following command to list the private GPG key you just created:
 
     ```
-    gpg --list-secret-keys --keyid-format LONG mr@robot.sh
+    gpg --list-secret-keys --keyid-format LONG <your_email>
     ```
 
-    Replace `mr@robot.sh` with the email address you entered above.
+    Replace `<your_email>` with the email address you entered above.
 
 1. Copy the GPG key ID that starts with `sec`. In the following example, that's
    `30F2B65B9246B6CA`:
@@ -132,7 +124,7 @@ started:
     ```
     sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
           D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
-    uid                   [ultimate] Mr. Robot <mr@robot.sh>
+    uid                   [ultimate] Mr. Robot <your_email>
     ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
     ```
 
@@ -146,7 +138,7 @@ started:
 
 ## Adding a GPG key to your account
 
->**Note:**
+NOTE: **Note:**
 Once you add a key, you cannot edit it, only remove it. In case the paste
 didn't work, you'll have to remove the offending key and re-add it.
 
@@ -174,11 +166,11 @@ key to use.
 
 1. Use the following command to list the private GPG key you just created:
 
-    ```
-    gpg --list-secret-keys --keyid-format LONG mr@robot.sh
+    ```sh
+    gpg --list-secret-keys --keyid-format LONG <your_email>
     ```
 
-    Replace `mr@robot.sh` with the email address you entered above.
+    Replace `<your_email>` with the email address you entered above.
 
 1. Copy the GPG key ID that starts with `sec`. In the following example, that's
    `30F2B65B9246B6CA`:
@@ -186,18 +178,27 @@ key to use.
     ```
     sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
           D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA
-    uid                   [ultimate] Mr. Robot <mr@robot.sh>
+    uid                   [ultimate] Mr. Robot <your_email>
     ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
     ```
 
 1. Tell Git to use that key to sign the commits:
 
-    ```
+    ```sh
     git config --global user.signingkey 30F2B65B9246B6CA
     ```
 
     Replace `30F2B65B9246B6CA` with your GPG key ID.
 
+
+1. (Optional) If Git is using `gpg` and you get errors like `secret key not available`
+   or `gpg: signing failed: secret key not available`, run the following command to
+   change to `gpg2`:
+
+   ```sh
+   git config --global gpg.program gpg2
+   ```
+
 ## Signing commits
 
 After you have [created your GPG key](#generating-a-gpg-key) and [added it to
@@ -261,4 +262,7 @@ To remove a GPG key from your account:
 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
+## Rejecting commits that are not signed **[PREMIUM]**
+
+You can configure your project to reject commits that aren't GPG-signed
+via [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html).