Merge branch 'aqualls-signing-commits' into 'master'

CTRT revision of GPG signing page

See merge request gitlab-org/gitlab!82541

doc/user/project/repository/gpg_signed_commits/index.md

@@ -6,129 +6,96 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Signing commits with GPG **(FREE)**
 
-You can use a GPG key to sign Git commits made in a GitLab repository. Signed
-commits are labeled **Verified** if the identity of the committer can be
-verified. To verify the identity of a committer, GitLab requires their public
-GPG key.
+You can sign the commits you make in a GitLab repository with a
+GPG ([GNU Privacy Guard](https://gnupg.org/)) key. When you add a cryptographic
+signature to your commit, you provide extra assurance that a commit
+originated from you, rather than an impersonator. If GitLab can verify a commit
+author's identity with a public GPG key, the commit is marked **Verified** in the
+GitLab UI. You can then configure [push rules](../push_rules.md#enabling-push-rules)
+for your project to reject individual commits not signed with GPG, or reject all
+commits from unverified users.
 
 NOTE:
-The term GPG is used for all OpenPGP/PGP/GPG related material and
+GitLab uses the term GPG for all OpenPGP, PGP, and GPG-related material and
 implementations.
 
-To view a user's public GPG key, you can:
-
-- Go to `https://gitlab.example.com/<username>.gpg`.
-- Select **View public GPG keys** (**{key}**) in the top right of the user's profile.
-
-GPG verified tags are not supported yet.
-
-See the [further reading](#further-reading) section for more details on GPG.
-
-## How GitLab handles GPG
-
-GitLab uses its own keyring to verify the GPG signature. It does not access any
-public key server.
-
-For a commit to be verified by GitLab:
+For GitLab to consider a commit verified:
 
 - The committer must have a GPG public/private key pair.
-- The committer's public key must have been uploaded to their GitLab
-  account.
-- One of the emails in the GPG key must match a **verified** email address
-  used by the committer in GitLab. This address will be part of the public key.
-  If you want to keep this address private, use the automatically generated
+- The committer's public key must be uploaded to their GitLab account.
+- One of the email addresses in the GPG public key must match a **verified** email address
+  used by the committer in GitLab. To keep this address private, use the automatically generated
   [private commit email address](../../../profile/index.md#use-an-automatically-generated-private-commit-email)
   GitLab provides in your profile.
 - The committer's email address must match the verified email address from the
   GPG key.
 
-## Generating a GPG key
-
-If you don't already have a GPG key, the following steps can help you get
-started:
-
-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 command appropriate for your version
-   of `gpg`. This command spawns a series of questions:
-
-   ```shell
-   # Use this command for the default version of gpg, including
-   # Gpg4win on Windows, and most macOS versions:
-   gpg --gen-key
+GitLab uses its own keyring to verify the GPG signature. It does not access any
+public key server.
 
-   # Use this command for versions of GPG later than 2.1.17:
-   gpg --full-gen-key
-   ```
+GPG verified tags are not supported.
 
-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):
+For more details about GPG, refer to the [related topics list](#related-topics).
 
-   ```plaintext
-   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
-   ```
+## View a user's public GPG key
 
-1. The next question is key length. We recommend you choose `4096`:
+To view a user's public GPG key, you can either:
 
-   ```plaintext
-   RSA keys may be between 1024 and 4096 bits long.
-   What keysize do you want? (2048) 4096
-   Requested keysize is 4096 bits
-   ```
+- Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key,
+  if the user has configured one, or a blank page for users without a configured GPG key.
+- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the top right
+  of the user's profile, select **View public GPG keys** (**{key}**).
 
-1. Specify the validity period of your key. This is something
-   subjective, and you can use the default value, which is to never expire:
+## Configure commit signing
 
-   ```plaintext
-   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
-   ```
+To sign commits, you must configure both your local machine and your GitLab account:
 
-1. Confirm that the answers you gave were correct by typing `y`:
+1. [Create a GPG key](#create-a-gpg-key).
+1. [Add a GPG key to your account](#add-a-gpg-key-to-your-account).
+1. [Associate your GPG key with Git](#associate-your-gpg-key-with-git).
+1. [Sign your Git commits](#sign-your-git-commits).
 
-   ```plaintext
-   Is this correct? (y/N) y
-   ```
+### Create a GPG key
 
-1. Enter your real name, the email address to be associated with this key
-   (should match a verified email address you use in GitLab) and an optional
-   comment (press <kbd>Enter</kbd> to skip):
+If you don't already have a GPG key, create one:
 
-   ```plaintext
-   GnuPG needs to construct a user ID to identify your key.
+1. [Install GPG](https://www.gnupg.org/download/) for your operating system.
+   If your operating system has `gpg2` installed, replace `gpg` with `gpg2` in
+   the commands on this page.
+1. To generate your key pair, run the command appropriate for your version of `gpg`:
 
-   Real name: Mr. Robot
-   Email address: <your_email>
-   Comment:
-   You selected this USER-ID:
-       "Mr. Robot <your_email>"
+   ```shell
+   # Use this command for the default version of GPG, including
+   # Gpg4win on Windows, and most macOS versions:
+   gpg --gen-key
 
-   Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
+   # Use this command for versions of GPG later than 2.1.17:
+   gpg --full-gen-key
    ```
 
-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:
+1. Select the algorithm your key should use, or press <kbd>Enter</kbd> to select
+   the default option, `RSA and RSA`.
+1. Select the key length, in bits. GitLab recommends 4096-bit keys.
+1. Specify the validity period of your key. This value is subjective, and the
+   default value is no expiration.
+1. To confirm your answers, enter `y`.
+1. Enter your name.
+1. Enter your email address. It must match a
+   [verified email address](../../../profile/index.md#change-the-email-displayed-on-your-commits)
+   in your GitLab account.
+1. Optional. Enter a comment to display in parentheses after your name.
+1. GPG displays the information you've entered so far. Edit the information or press
+   <kbd>O</kbd> (for `Okay`) to continue.
+1. Enter a strong password, then enter it again to confirm it.
+1. To list your private GPG key, run this command, replacing
+   `<EMAIL>` with the email address you used when you generated the key:
 
    ```shell
-   gpg --list-secret-keys --keyid-format LONG <your_email>
+   gpg --list-secret-keys --keyid-format LONG <EMAIL>
    ```
 
-   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`:
+1. In the output, identify the `sec` line, and copy the GPG key ID. It begins after
+   the `/` character. In this example, the key ID is `30F2B65B9246B6CA`:
 
    ```plaintext
    sec   rsa4096/30F2B65B9246B6CA 2017-08-18 [SC]
@@ -137,49 +104,46 @@ started:
    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
    ```
 
-1. Export the public key of that ID (replace your key ID from the previous step):
+1. To show the associated public key, run this command, replacing `<ID>` with the
+   GPG key ID from the previous step:
 
    ```shell
-   gpg --armor --export 30F2B65B9246B6CA
+   gpg --armor --export <ID>
    ```
 
-1. Finally, copy the public key and [add it in your user settings](#adding-a-gpg-key-to-your-account)
+1. Copy the public key, including the `BEGIN PGP PUBLIC KEY BLOCK` and
+   `END PGP PUBLIC KEY BLOCK` lines. You need this key in the next step.
 
-## Adding a GPG key to your account
+### Add a GPG key to your account
 
-NOTE:
-After you add a key, you cannot edit it, only remove it. In case the paste
-didn't work, you have to remove the offending key and re-add it.
-
-You can add a GPG key in your user settings:
+To add a GPG key to your user settings:
 
+1. Sign in to GitLab.
 1. In the top-right corner, select your avatar.
 1. Select **Edit profile**.
-1. On the left sidebar, select **GPG Keys**.
-1. Paste your _public_ key in the **Key** text box.
-
-   ![Paste GPG public key](img/profile_settings_gpg_keys_paste_pub.png)
-
-1. Select **Add key** to add it to GitLab. You can see the key's fingerprint, the corresponding
-   email address, and creation date.
+1. On the left sidebar, select **GPG Keys** (**{key}**).
+1. In **Key**, paste your _public_ key.
+1. To add the key to your account, select **Add key**. GitLab shows the key's
+   fingerprint, email address, and creation date:
 
    ![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
 
-## Associating your GPG key with Git
+After you add a key, you cannot edit it. Instead, remove the offending key and re-add it.
 
-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.
+### Associate your GPG key with Git
 
-1. Use the following command to list the private GPG key you just created:
+After you [create your GPG key](#create-a-gpg-key) and
+[add it to your account](#add-a-gpg-key-to-your-account), you must configure Git
+to use this key:
+
+1. Run this command to list the private GPG key you just created,
+   replacing `<EMAIL>` with the email address for your key:
 
    ```shell
-   gpg --list-secret-keys --keyid-format LONG <your_email>
+   gpg --list-secret-keys --keyid-format LONG <EMAIL>
    ```
 
-   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
+1. Copy the GPG private key ID that starts with `sec`. In this example, the private key ID is
    `30F2B65B9246B6CA`:
 
    ```plaintext
@@ -189,114 +153,103 @@ key to use.
    ssb   rsa4096/B7ABC0813E4028C0 2017-08-18 [E]
    ```
 
-1. Tell Git to use that key to sign the commits:
+1. Run this command to configure Git to sign your commits with your key,
+   replacing `<KEY ID>` with your GPG key ID:
 
    ```shell
-   git config --global user.signingkey 30F2B65B9246B6CA
+   git config --global user.signingkey <KEY ID>
    ```
 
-   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`:
+1. Optional. If Git uses `gpg` and you get errors like `secret key not available`
+   or `gpg: signing failed: secret key not available`, run this command to
+   use `gpg2` instead:
 
    ```shell
    git config --global gpg.program gpg2
    ```
 
-## Signing commits
+### Sign your Git 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:
+After you [add your public key to your account](#add-a-gpg-key-to-your-account),
+you can sign individual commits manually, or configure Git to default to signed commits:
 
-1. Commit like you used to, the only difference is the addition of the `-S` flag:
+- Sign individual Git commits manually:
+  1. Add `-S` flag to any commit you want to sign:
 
-   ```shell
-   git commit -S -m "My commit msg"
-   ```
+     ```shell
+     git commit -S -m "My commit message"
+     ```
 
-1. Enter the passphrase of your GPG key when asked.
-1. Push to GitLab and check that your commits [are verified](#verifying-commits).
+  1. Enter the passphrase of your GPG key when asked.
+  1. Push to GitLab and check that your commits [are verified](#verify-commits).
+- Sign all Git commits by default by running this command:
 
-If you don't want to type the `-S` flag every time you commit, you can tell Git
-to sign your commits automatically:
+  ```shell
+  git config --global commit.gpgsign true
+  ```
 
-```shell
-git config --global commit.gpgsign true
-```
+## Verify commits
 
-## Verifying commits
+You can review commits for a merge request, or for an entire project:
 
-1. Within a project or [merge request](../../merge_requests/index.md), navigate to
-   the **Commits** tab. Signed commits show a badge containing either
-   **Verified** or **Unverified**, depending on the verification status of the GPG
-   signature.
+1. To review commits for a project:
+   1. On the top bar, select **Menu > Projects** and find your project.
+   1. On the left sidebar, select **Repository > Commits**.
+1. To review commits for a merge request:
+   1. On the top bar, select **Menu > Projects** and find your project.
+   1. On the left sidebar, select **Merge requests**, then select your merge request.
+   1. Select **Commits**.
+1. Identify the commit you want to review. Signed commits show either a **Verified**
+   or **Unverified** badge, depending on the verification status of the GPG
+   signature. Unsigned commits do not display a badge:
 
    ![Signed and unsigned commits](img/project_signed_and_unsigned_commits.png)
 
-1. By clicking on the GPG badge, details of the signature are displayed.
+1. To display the signature details for a commit, select the GPG badge:
 
    ![Signed commit with verified signature](img/project_signed_commit_verified_signature.png)
 
-   ![Signed commit with verified signature](img/project_signed_commit_unverified_signature.png)
+   ![Signed commit with unverified signature](img/project_signed_commit_unverified_signature.png)
 
-## Revoking a GPG key
+## Revoke a GPG key
 
-Revoking a key **unverifies** already signed commits. Commits that were
-verified by using this key changes to an unverified state. Future commits
-stay unverified after you revoke this key. This action should be used
-in case your key has been compromised.
+If a GPG key becomes compromised, revoke it. Revoking a key changes both future and past commits:
+
+- Past commits signed by this key are marked as unverified.
+- Future commits signed by this key are marked as unverified.
 
 To revoke a GPG key:
 
 1. In the top-right corner, select your avatar.
 1. Select **Edit profile**.
-1. On the left sidebar, select **GPG Keys**.
+1. On the left sidebar, select **GPG Keys** (**{key}**).
 1. Select **Revoke** next to the GPG key you want to delete.
 
-## Removing a GPG key
+## Remove a GPG key
+
+When you remove a GPG key from your GitLab account:
 
-Removing a key **does not unverify** already signed commits. Commits that were
-verified by using this key stay verified. Only unpushed commits stay
-unverified after you remove this key. To unverify already signed commits, you need
-to [revoke the associated GPG key](#revoking-a-gpg-key) from your account.
+- Previous commits signed with this key remain verified.
+- Future commits (including any commits created but not yet pushed) that attempt
+  to use this key are unverified.
 
 To remove a GPG key from your account:
 
 1. In the top-right corner, select your avatar.
 1. Select **Edit profile**.
-1. On the left sidebar, select **GPG Keys**.
-1. Select the trash icon (**{remove}**) next to the GPG key you want to delete.
-
-## Rejecting commits that are not signed **(PREMIUM)**
-
-You can configure your project to reject commits that aren't GPG-signed
-via [push rules](../push_rules.md).
-
-## GPG signing API
-
-Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit).
-
-## Further reading
-
-For more details about GPG, see:
-
-- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
-- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
-- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
-- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
-- [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys)
-
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+1. On the left sidebar, select **GPG Keys** (**{key}**).
+1. Select **Remove** (**{remove}**) next to the GPG key you want to delete.
+
+If you must unverify both future and past commits,
+[revoke the associated GPG key](#revoke-a-gpg-key) instead.
+
+## Related topics
+
+- [Sign commits and tags with X.509 certificates](../x509_signed_commits/index.md)
+- [Commits API](../../../../api/commits.md)
+- GPG resources:
+  - [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+  - [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys)
+  - [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices)
+  - [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced)
+  - [Review existing GPG keys in your instance](../../../admin_area/credentials_inventory.md#review-existing-gpg-keys)

doc/user/project/repository/x509_signed_commits/index.md

@@ -20,7 +20,7 @@ The main difference is the way GitLab determines whether or not the developer's
   (A trust store is a repository of trusted security certificates.) Combined with
   any required intermediate certificates in the signature, the developer's certificate
   can be chained back to a trusted root certificate.
-- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#adding-a-gpg-key-to-your-account)
+- For GPG, developers [add their GPG key](../gpg_signed_commits/index.md#add-a-gpg-key-to-your-account)
   to their account.
 
 GitLab uses its own certificate store and therefore defines the