documentation for gpg signed commits

8 files changed, 56 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index ac7311a8c13..5537f54ab2b 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -89,6 +89,7 @@ Manage files and branches from the UI (user interface):
 - [Git](topics/git/index.md): Getting started with Git, branching strategies, Git LFS, advanced use.
 - [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf): Download a PDF describing the most used Git operations.
 - [GitLab Flow](workflow/gitlab_flow.md): explore the best of Git with the GitLab Flow strategy.
+- [Signing commits](workflow/gpg_signed_commits/index.md): use GPG to sign your commits.
 
 ### Migrate and import your projects from other platforms
 
diff --git a/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys.png b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys.png
new file mode 100644
index 00000000000..e525083918b
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys.png
diff --git a/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png
new file mode 100644
index 00000000000..8e26d98f1b0
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png
diff --git a/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png
new file mode 100644
index 00000000000..f715c46adc3
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png
diff --git a/doc/workflow/gpg_signed_commits/img/project_signed_and_unsigned_commits.png b/doc/workflow/gpg_signed_commits/img/project_signed_and_unsigned_commits.png
new file mode 100644
index 00000000000..16ec2d031ae
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/project_signed_and_unsigned_commits.png
diff --git a/doc/workflow/gpg_signed_commits/img/project_signed_commit_unverified_signature.png b/doc/workflow/gpg_signed_commits/img/project_signed_commit_unverified_signature.png
new file mode 100644
index 00000000000..22565cf7c7e
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/project_signed_commit_unverified_signature.png
diff --git a/doc/workflow/gpg_signed_commits/img/project_signed_commit_verified_signature.png b/doc/workflow/gpg_signed_commits/img/project_signed_commit_verified_signature.png
new file mode 100644
index 00000000000..1778b2ddf2b
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/img/project_signed_commit_verified_signature.png
diff --git a/doc/workflow/gpg_signed_commits/index.md b/doc/workflow/gpg_signed_commits/index.md
new file mode 100644
index 00000000000..041c681ba63
--- /dev/null
+++ b/doc/workflow/gpg_signed_commits/index.md
@@ -0,0 +1,55 @@
+# Signing commits with GPG
+
+## Getting started
+
+- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work)
+
+## How GitLab handles GPG
+
+GitLab uses its own keyring to verify the GPG signature. It does not access any
+public key server.
+
+In order to have a commit verified on GitLab the corresponding public key needs
+to be uploaded to GitLab.
+
+For a signature to be verified two prerequisites need to be met:
+
+1. The public key needs to be added to GitLab
+1. One of the emails in the GPG key matches your **primary** email
+
+## Add a GPG key
+
+1. On the upper right corner, click on your avatar and go to your **Settings**.
+
+    ![Settings dropdown](../../gitlab-basics/img/profile_settings.png)
+
+1. Navigate to the **GPG keys** tab.
+
+    ![GPG Keys](img/profile_settings_gpg_keys.png)
+
+1. Paste your **public** key in the 'Key' box.
+
+    ![Paste GPG public key](img/profile_settings_gpg_keys_paste_pub.png)
+
+1. Finally, click on **Add key** to add it to GitLab. You will be able to see
+   its fingerprint, the corresponding email address and creation date.
+
+    ![GPG key single page](img/profile_settings_gpg_keys_single_key.png)
+
+>**Note:**
+Once you add a key, you cannot edit it, only remove it. In case the paste
+didn't work, you will have to remove the offending key and re-add it.
+
+## Verifying commits
+
+1. Within a project navigate to the **Commits** tag. 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)