1 files changed, 52 insertions, 19 deletions
diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md
index 19238839a5e..20143af0b33 100644
--- a/doc/user/project/repository/x509_signed_commits/index.md
+++ b/doc/user/project/repository/x509_signed_commits/index.md
@@ -2,21 +2,21 @@
 type: concepts, howto
 ---
 
-# Signing commits with x509
+# Signing commits and tags with X.509
 
-[x509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key
+[X.509](https://en.wikipedia.org/wiki/X.509) is a standard format for public key
 certificates issued by a public or private Public Key Infrastructure (PKI).
-Personal x509 certificates are used for authentication or signing purposes
+Personal X.509 certificates are used for authentication or signing purposes
 such as SMIME, but Git also supports signing of commits and tags
-with x509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md).
-The main difference is the trust anchor which is the PKI for x509 certificates
+with X.509 certificates in a similar way as with [GPG](../gpg_signed_commits/index.md).
+The main difference is the trust anchor which is the PKI for X.509 certificates
 instead of a web of trust with GPG.
 
-## How GitLab handles x509
+## How GitLab handles X.509
 
 GitLab uses its own certificate store and therefore defines the trust chain.
 
-For a commit to be *verified* by GitLab:
+For a commit or tag to be *verified* by GitLab:
 
 - The signing certificate email must match a verified email address used by the committer in GitLab.
 - The Certificate Authority has to be trusted by the GitLab instance, see also
@@ -25,9 +25,14 @@ For a commit to be *verified* by GitLab:
   which is usually up to three years.
 - The signing time is equal or later then commit time.
 
-NOTE: **Note:** There is no certificate revocation list check in place at the moment.
+NOTE: **Note:** Certificate revocation lists are checked on a daily basis via background worker.
 
-## Obtaining an x509 key pair
+NOTE: **Note:** Self signed certificates without `authorityKeyIdentifier`,
+`subjectKeyIdentifier`, and `crlDistributionPoints` are not supported. We
+recommend using certificates from a PKI that are in line with
+[RFC 5280](https://tools.ietf.org/html/rfc5280).
+
+## Obtaining an X.509 key pair
 
 If your organization has Public Key Infrastructure (PKI), that PKI will provide
 an S/MIME key.
@@ -37,12 +42,12 @@ own self-signed one, or purchase one. MozillaZine keeps a nice collection
 of [S/MIME-capable signing authorities](http://kb.mozillazine.org/Getting_an_SMIME_certificate)
 and some of them generate keys for free.
 
-## Associating your x509 certificate with Git
+## Associating your X.509 certificate with Git
 
-To take advantage of X509 signing, you will need Git 2.19.0 or later. You can
+To take advantage of X.509 signing, you will need Git 2.19.0 or later. You can
 check your Git version with:
 
-```sh
+```shell
 git --version
 ```
 
@@ -52,7 +57,7 @@ If you have the correct version, you can proceed to configure Git.
 
 Configure Git to use your key for signing:
 
-```sh
+```shell
 signingkey = $( gpgsm --list-secret-keys | egrep '(key usage|ID)' | grep -B 1 digitalSignature | awk '/ID/ {print $2}' )
 git config --global user.signingkey $signingkey
 git config --global gpg.format x509
@@ -64,21 +69,21 @@ Install [smimesign](https://github.com/github/smimesign) by downloading the
 installer or via `brew install smimesign` on MacOS.
 
 Get the ID of your certificate with `smimesign --list-keys` and set your
-signingkey `git config --global user.signingkey ID`, then configure x509:
+signingkey `git config --global user.signingkey ID`, then configure X.509:
 
-```sh
+```shell
 git config --global gpg.x509.program smimesign
 git config --global gpg.format x509
 ```
 
 ## Signing commits
 
-After you have [associated your x509 certificate with Git](#associating-your-x509-certificate-with-git) you
+After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you
 can start signing your commits:
 
 1. Commit like you used to, the only difference is the addition of the `-S` flag:
 
-   ```sh
+   ```shell
    git commit -S -m "feat: x509 signed commits"
    ```
 
@@ -87,7 +92,7 @@ can start signing your commits:
 If you don't want to type the `-S` flag every time you commit, you can tell Git
 to sign your commits automatically:
 
-```sh
+```shell
 git config --global commit.gpgsign true
 ```
 
@@ -95,6 +100,34 @@ git config --global commit.gpgsign true
 
 To verify that a commit is signed, you can use the `--show-signature` flag:
 
-```sh
+```shell
 git log --show-signature
 ```
+
+## Signing tags
+
+After you have [associated your X.509 certificate with Git](#associating-your-x509-certificate-with-git) you
+can start signing your tags:
+
+1. Tag like you used to, the only difference is the addition of the `-s` flag:
+
+   ```shell
+   git tag -s v1.1.1 -m "My signed tag"
+   ```
+
+1. Push to GitLab and check that your tags [are verified](#verifying-tags).
+
+If you don't want to type the `-s` flag every time you tag, you can tell Git
+to sign your tags automatically:
+
+```shell
+git config --global tag.gpgsign true
+```
+
+## Verifying tags
+
+To verify that a tag is signed, you can use the `--verify` flag:
+
+```shell
+git tag --verify v1.1.1
+```