Merge branch 'master' of gitlab_gitlab:gitlab-org/gitlab-cerunner-metrics-extractor

15 files changed, 807 insertions, 643 deletions

diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md
index d8094587d14..2fc9db0632e 100644
--- a/doc/administration/auth/README.md
+++ b/doc/administration/auth/README.md
@@ -1,19 +1,34 @@
 ---
 comments: false
+type: index
 ---
 
-# Authentication and Authorization
+# GitLab authentication and authorization
 
 GitLab integrates with the following external authentication and authorization
-providers.
+providers:
 
-- [LDAP](ldap.md) Includes Active Directory, Apple Open Directory, Open LDAP,
-  and 389 Server
+- [Auth0](../../integration/auth0.md)
+- [Authentiq](authentiq.md)
+- [Azure](../../integration/azure.md)
+- [Bitbucket Cloud](../../integration/bitbucket.md)
+- [CAS](../../integration/cas.md)
+- [Crowd](../../integration/crowd.md)
+- [Facebook](../../integration/facebook.md)
+- [GitHub](../../integration/github.md)
+- [GitLab.com](../../integration/gitlab.md)
+- [Google](../../integration/google.md)
+- [JWT](jwt.md)
+- [Kerberos](../../integration/kerberos.md)
+- [LDAP](ldap.md): Includes Active Directory, Apple Open Directory, Open LDAP,
+  and 389 Server.
   - [LDAP for GitLab EE](ldap-ee.md): LDAP additions to GitLab Enterprise Editions **(STARTER ONLY)**
-- [OmniAuth](../../integration/omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google,
-  Bitbucket, Facebook, Shibboleth, Crowd, Azure, Authentiq ID, and JWT
-- [CAS](../../integration/cas.md) Configure GitLab to sign in using CAS
-- [SAML](../../integration/saml.md) Configure GitLab as a SAML 2.0 Service Provider
-- [Okta](okta.md) Configure GitLab to sign in using Okta
-- [Authentiq](authentiq.md): Enable the Authentiq OmniAuth provider for passwordless authentication
-- [Smartcard](smartcard.md) Smartcard authentication **(PREMIUM ONLY)**
+  - [Google Secure LDAP](google_secure_ldap.md)
+- [Okta](okta.md)
+- [Salesforce](../../integration/salesforce.md)
+- [SAML](../../integration/saml.md)
+- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)**
+- [Shibboleth](../../integration/shibboleth.md)
+- [Smartcard](smartcard.md) **(PREMIUM ONLY)**
+- [Twitter](../../integration/twitter.md)
+- [UltraAuth](../../integration/ultra_auth.md)
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md
index 726622d8599..b84eca4ef0d 100644
--- a/doc/administration/auth/authentiq.md
+++ b/doc/administration/auth/authentiq.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Authentiq OmniAuth Provider
 
 To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq.
@@ -8,47 +12,48 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t
 
 1. On your GitLab server, open the configuration file:
 
-    For omnibus installation
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
+   For omnibus installation
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    For installations from source:
+   For installations from source:
 
-    ```sh
-    sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
-    ```
+   ```sh
+   sudo -u git -H editor /home/git/gitlab/config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings to enable single sign-on and add Authentiq as an OAuth provider.
 
 1. Add the provider configuration for Authentiq:
 
-    For Omnibus packages:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        "name" => "authentiq",
-        "app_id" => "YOUR_CLIENT_ID",
-        "app_secret" => "YOUR_CLIENT_SECRET",
-        "args" => {
-               "scope": 'aq:name email~rs address aq:push'
-         }
-      }
-    ]
-    ```
-
-    For installations from source:
-
-    ```yaml
-    - { name: 'authentiq',
-        app_id: 'YOUR_CLIENT_ID',
-        app_secret: 'YOUR_CLIENT_SECRET',
-        args: {
-               scope: 'aq:name email~rs address aq:push'
-              }
-      }
-    ```
+   For Omnibus packages:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       "name" => "authentiq",
+       "app_id" => "YOUR_CLIENT_ID",
+       "app_secret" => "YOUR_CLIENT_SECRET",
+       "args" => {
+              "scope": 'aq:name email~rs address aq:push'
+        }
+     }
+   ]
+   ```
+
+   For installations from source:
+
+   ```yaml
+   - { name: 'authentiq',
+       app_id: 'YOUR_CLIENT_ID',
+       app_secret: 'YOUR_CLIENT_SECRET',
+       args: {
+              scope: 'aq:name email~rs address aq:push'
+             }
+     }
+   ```
 
 1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits.
    See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers.
@@ -65,3 +70,15 @@ On the sign in page there should now be an Authentiq icon below the regular sign
 - If not they will be prompted to download the app and then follow the procedure above.
 
 If everything goes right, the user will be returned to GitLab and will be signed in.
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md
index 6db74958d5a..ac63b4f2b97 100644
--- a/doc/administration/auth/crowd.md
+++ b/doc/administration/auth/crowd.md
@@ -1,60 +1,67 @@
+---
+type: reference
+---
+
 # Atlassian Crowd OmniAuth Provider
 
+Authenticate to GitLab using the Atlassian Crowd OmniAuth provider.
+
 ## Configure a new Crowd application
 
 1. Choose 'Applications' in the top menu, then 'Add application'.
 1. Go through the 'Add application' steps, entering the appropriate details.
    The screenshot below shows an example configuration.
 
-    ![Example Crowd application configuration](img/crowd_application.png)
+   ![Example Crowd application configuration](img/crowd_application.png)
 
 ## Configure GitLab
 
 1. On your GitLab server, open the configuration file.
 
-    **Omnibus:**
+   **Omnibus:**
 
-    ```sh
-      sudo editor /etc/gitlab/gitlab.rb
-    ```
+   ```sh
+     sudo editor /etc/gitlab/gitlab.rb
+   ```
 
-    **Source:**
+   **Source:**
 
-    ```sh
-      cd /home/git/gitlab
+   ```sh
+     cd /home/git/gitlab
 
-      sudo -u git -H editor config/gitlab.yml
-    ```
+     sudo -u git -H editor config/gitlab.yml
+   ```
 
 1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
    for initial settings.
 
 1. Add the provider configuration:
 
-    **Omnibus:**
-
-    ```ruby
-      gitlab_rails['omniauth_providers'] = [
-        {
-          "name" => "crowd",
-          "args" => {
-            "crowd_server_url" => "CROWD_SERVER_URL",
-            "application_name" => "YOUR_APP_NAME",
-            "application_password" => "YOUR_APP_PASSWORD"
-          }
-        }
-      ]
-    ```
-
-    **Source:**
-
-    ```
-       - { name: 'crowd',
-           args: {
-             crowd_server_url: 'CROWD_SERVER_URL',
-             application_name: 'YOUR_APP_NAME',
-             application_password: 'YOUR_APP_PASSWORD' } }
-    ```
+   **Omnibus:**
+
+   ```ruby
+     gitlab_rails['omniauth_providers'] = [
+       {
+         "name" => "crowd",
+         "args" => {
+           "crowd_server_url" => "CROWD_SERVER_URL",
+           "application_name" => "YOUR_APP_NAME",
+           "application_password" => "YOUR_APP_PASSWORD"
+         }
+       }
+     ]
+   ```
+
+   **Source:**
+
+   ```
+      - { name: 'crowd',
+          args: {
+            crowd_server_url: 'CROWD_SERVER_URL',
+            application_name: 'YOUR_APP_NAME',
+            application_password: 'YOUR_APP_PASSWORD' } }
+   ```
+
 1. Change `CROWD_SERVER_URL` to the URL of your Crowd server.
 1. Change `YOUR_APP_NAME` to the application name from Crowd applications page.
 1. Change `YOUR_APP_PASSWORD` to the application password you've set.
@@ -77,4 +84,4 @@ could not authorize you from Crowd because invalid credentials
 
 Please make sure the Crowd users who need to login to GitLab are authorized to [the application](#configure-a-new-crowd-application) in the step of **Authorisation**. This could be verified by try "Authentication test" for Crowd as of 2.11.
 
-![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
\ No newline at end of file
+![Example Crowd application authorisation configuration](img/crowd_application_authorisation.png)
diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md
index 1db5bb4bc3f..55e6f53622c 100644
--- a/doc/administration/auth/google_secure_ldap.md
+++ b/doc/administration/auth/google_secure_ldap.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Google Secure LDAP **(CORE ONLY)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46391) in GitLab 11.9.
@@ -66,7 +70,7 @@ values obtained during the LDAP client configuration earlier:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
+   ```ruby
    gitlab_rails['ldap_enabled'] = true
    gitlab_rails['ldap_servers'] = YAML.load <<-EOS # remember to close this block with 'EOS' below
      main: # 'main' is the GitLab 'provider ID' of this LDAP server
@@ -127,7 +131,7 @@ values obtained during the LDAP client configuration earlier:
            AcZSFJQjdg5BTyvdEDhaYUKGdRw=
            -----END PRIVATE KEY-----
    EOS
-    ```
+   ```
 
 1. Save the file and [reconfigure] GitLab for the changes to take effect.
 
@@ -137,7 +141,7 @@ values obtained during the LDAP client configuration earlier:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
+   ```yaml
    ldap:
      enabled: true
      servers:
@@ -204,3 +208,15 @@ values obtained during the LDAP client configuration earlier:
 
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
index 320a65b665d..86dd398343b 100644
--- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
+++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md
@@ -1,15 +1,9 @@
 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 
 # How to configure LDAP with GitLab CE
 
-## Introduction
-
 Managing a large number of users in GitLab can become a burden for system administrators. As an organization grows so do user accounts. Keeping these user accounts in sync across multiple enterprise applications often becomes a time consuming task.
 
 In this guide we will focus on configuring GitLab with Active Directory. [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) is a popular LDAP compatible directory service provided by Microsoft, included in all modern Windows Server operating systems.
@@ -268,3 +262,15 @@ have extended functionalities with LDAP, such as:
 - Multiple LDAP servers
 
 Read through the article on [LDAP for GitLab EE](../how_to_configure_ldap_gitlab_ee/index.md) **(STARTER ONLY)** for an overview.
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
index 2683950f143..366acb9ed3e 100644
--- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
+++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md
@@ -1,16 +1,10 @@
 ---
-author: Chris Wilson
-author_gitlab: MrChrisW
-level: intermediary
-article_type: admin guide
-date: 2017-05-03
+type: howto
 ---
 
 # How to configure LDAP with GitLab EE **(STARTER ONLY)**
 
-## Introduction
-
-The present article follows [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
+This article expands on [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward.
 
 ## GitLab Enterprise Edition - LDAP features
 
@@ -117,3 +111,15 @@ Integration of GitLab with Active Directory (LDAP) reduces the complexity of use
 It has the advantage of improving user permission controls, whilst easing the deployment of GitLab into an existing [IT environment](https://www.techopedia.com/definition/29199/it-infrastructure). GitLab EE offers advanced group management and multiple LDAP servers.
 
 With the assistance of the [GitLab Support](https://about.gitlab.com/support) team, setting up GitLab with an existing AD/LDAP solution will be a smooth and painless process.
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/img/google_secure_ldap_add_step_1.png b/doc/administration/auth/img/google_secure_ldap_add_step_1.png
index fd254443d75..bee9c602a14 100644
--- a/doc/administration/auth/img/google_secure_ldap_add_step_1.png
+++ b/doc/administration/auth/img/google_secure_ldap_add_step_1.png
diff --git a/doc/administration/auth/img/google_secure_ldap_add_step_2.png b/doc/administration/auth/img/google_secure_ldap_add_step_2.png
index 611a21ae03c..b127410cb8c 100644
--- a/doc/administration/auth/img/google_secure_ldap_add_step_2.png
+++ b/doc/administration/auth/img/google_secure_ldap_add_step_2.png
diff --git a/doc/administration/auth/img/google_secure_ldap_client_settings.png b/doc/administration/auth/img/google_secure_ldap_client_settings.png
index 3c0b3f3d4bd..868e6645f56 100644
--- a/doc/administration/auth/img/google_secure_ldap_client_settings.png
+++ b/doc/administration/auth/img/google_secure_ldap_client_settings.png
diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md
index 497298503ad..e6b3287ce60 100644
--- a/doc/administration/auth/jwt.md
+++ b/doc/administration/auth/jwt.md
@@ -1,67 +1,71 @@
+---
+type: reference
+---
+
 # JWT OmniAuth provider
 
 To enable the JWT OmniAuth provider, you must register your application with JWT.
 JWT will provide you with a secret key for you to use.
 
-1.  On your GitLab server, open the configuration file.
-
-    For Omnibus GitLab:
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    For installations from source:
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-1.  See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
-1.  Add the provider configuration.
-
-    For Omnibus GitLab:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      { name: 'jwt',
-        args: {
-          secret: 'YOUR_APP_SECRET',
-          algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
-          uid_claim: 'email',
-          required_claims: ['name', 'email'],
-          info_maps: { name: 'name', email: 'email' },
-          auth_url: 'https://example.com/',
-          valid_within: 3600 # 1 hour
-        }
-      }
-    ]
-    ```
-
-    For installation from source:
-
-    ```
-    - { name: 'jwt',
-        args: {
-          secret: 'YOUR_APP_SECRET',
-          algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
-          uid_claim: 'email',
-          required_claims: ['name', 'email'],
-          info_map: { name: 'name', email: 'email' },
-          auth_url: 'https://example.com/',
-          valid_within: 3600 # 1 hour
-        }
-      }
-    ```
-
-    NOTE: **Note:** For more information on each configuration option refer to
-    the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
-
-1.  Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
-1.  Save the configuration file.
-1.  [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
-    installed GitLab via Omnibus or from source respectively.
+1. On your GitLab server, open the configuration file.
+
+   For Omnibus GitLab:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+1. Add the provider configuration.
+
+   For Omnibus GitLab:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     { name: 'jwt',
+       args: {
+         secret: 'YOUR_APP_SECRET',
+         algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
+         uid_claim: 'email',
+         required_claims: ['name', 'email'],
+         info_maps: { name: 'name', email: 'email' },
+         auth_url: 'https://example.com/',
+         valid_within: 3600 # 1 hour
+       }
+     }
+   ]
+   ```
+
+   For installation from source:
+
+   ```
+   - { name: 'jwt',
+       args: {
+         secret: 'YOUR_APP_SECRET',
+         algorithm: 'HS256', # Supported algorithms: 'RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512', 'HS256', 'HS384', 'HS512'
+         uid_claim: 'email',
+         required_claims: ['name', 'email'],
+         info_map: { name: 'name', email: 'email' },
+         auth_url: 'https://example.com/',
+         valid_within: 3600 # 1 hour
+       }
+     }
+   ```
+
+   NOTE: **Note:** For more information on each configuration option refer to
+   the [OmniAuth JWT usage documentation](https://github.com/mbleigh/omniauth-jwt#usage).
+
+1. Change `YOUR_APP_SECRET` to the client secret and set `auth_url` to your redirect URL.
+1. Save the configuration file.
+1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you
+   installed GitLab via Omnibus or from source respectively.
 
 On the sign in page there should now be a JWT icon below the regular sign in form.
 Click the icon to begin the authentication process. JWT will ask the user to
@@ -70,3 +74,15 @@ will be redirected to GitLab and will be signed in.
 
 [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure
 [restart GitLab]: ../restart_gitlab.md#installations-from-source
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md
index 1a8af0827ee..34f3cfa353f 100644
--- a/doc/administration/auth/ldap-ee.md
+++ b/doc/administration/auth/ldap-ee.md
@@ -1,36 +1,30 @@
-# LDAP Additions in GitLab EE **(STARTER ONLY)**
-
-This is a continuation of the main [LDAP documentation](ldap.md), detailing LDAP
-features specific to GitLab Enterprise Edition Starter, Premium and Ultimate.
+---
+type: reference
+---
 
-## Overview
+# LDAP Additions in GitLab EE **(STARTER ONLY)**
 
-[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
-stands for **Lightweight Directory Access Protocol**, which
-is a standard application protocol for
-accessing and maintaining distributed directory information services
-over an Internet Protocol (IP) network.
+This section documents LDAP features specific to to GitLab Enterprise Edition
+[Starter](https://about.gitlab.com/pricing/#self-managed) and above.
 
-GitLab integrates with LDAP to support **user authentication**. This integration
-works with most LDAP-compliant directory servers, including Microsoft Active
-Directory, Apple Open Directory, Open LDAP, and 389 Server.
-**GitLab Enterprise Edition** includes enhanced integration, including group
-membership syncing.
+For documentation relevant to both Community Edition and Enterprise Edition,
+see the main [LDAP documentation](ldap.md).
 
 ## Use cases
 
-- User sync: Once a day, GitLab will update users against LDAP
+- User sync: Once a day, GitLab will update users against LDAP.
 - Group sync: Once an hour, GitLab will update group membership
-  based on LDAP group members
+  based on LDAP group members.
 
-## Multiple LDAP servers
+## Multiple LDAP servers **(STARTER ONLY)**
 
 With GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
 that your GitLab instance will connect to.
 
-To add another LDAP server, you can start by duplicating the settings under
-[the main configuration](ldap.md#configuration) and edit them to match the
-additional LDAP server.
+To add another LDAP server:
+
+1. Duplicating the settings under [the main configuration](ldap.md#configuration).
+1. Edit them to match the additional LDAP server.
 
 Be sure to choose a different provider ID made of letters a-z and numbers 0-9.
 This ID will be stored in the database so that GitLab can remember which LDAP
@@ -43,19 +37,19 @@ users against LDAP.
 
 The process will execute the following access checks:
 
-1. Ensure the user is still present in LDAP
-1. If the LDAP server is Active Directory, ensure the user is active (not
-   blocked/disabled state). This will only be checked if
-   `active_directory: true` is set in the LDAP configuration [^1]
+- Ensure the user is still present in LDAP.
+- If the LDAP server is Active Directory, ensure the user is active (not
+  blocked/disabled state). This will only be checked if
+  `active_directory: true` is set in the LDAP configuration. [^1]
 
 The user will be set to `ldap_blocked` state in GitLab if the above conditions
 fail. This means the user will not be able to login or push/pull code.
 
 The process will also update the following user information:
 
-1. Email address
-1. If `sync_ssh_keys` is set, SSH public keys
-1. If Kerberos is enabled, Kerberos identity
+- Email address.
+- If `sync_ssh_keys` is set, SSH public keys.
+- If Kerberos is enabled, Kerberos identity.
 
 NOTE: **Note:**
 The LDAP sync process updates existing users while new users will
@@ -68,9 +62,6 @@ first time GitLab will trigger a sync for groups the user should be a member of.
 That way they don't need to wait for the hourly sync to be granted
 access to their groups and projects.
 
-In GitLab Premium, we can also add a GitLab group to sync with one or multiple LDAP groups or we can
-also add a filter. The filter must comply with the syntax defined in [RFC 2254](https://tools.ietf.org/search/rfc2254).
-
 A group sync process will run every hour on the hour, and `group_base` must be set
 in LDAP configuration for LDAP synchronizations based on group CN to work. This allows
 GitLab group membership to be automatically updated based on LDAP group members.
@@ -85,19 +76,19 @@ following.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## Base where we can search for groups
-      ##
-      ##   Ex. ou=groups,dc=gitlab,dc=example
-      ##
-      ##
-      group_base: ou=groups,dc=example,dc=com
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## Base where we can search for groups
+     ##
+     ##   Ex. ou=groups,dc=gitlab,dc=example
+     ##
+     ##
+     group_base: ou=groups,dc=example,dc=com
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -105,24 +96,37 @@ following.
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            group_base: ou=groups,dc=example,dc=com
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
----
-
 To take advantage of group sync, group owners or maintainers will need to create an
-LDAP group link in their group **Settings > LDAP Groups** page. Multiple LDAP
-groups and/or filters can be linked with a single GitLab group. When the link is
-created, an access level/role is specified (Guest, Reporter, Developer, Maintainer,
-or Owner).
+LDAP group link in their group **Settings > LDAP Groups** page.
+
+Multiple LDAP groups and [filters](#filters-premium-only) can be linked with
+a single GitLab group. When the link is created, an access level/role is
+specified (Guest, Reporter, Developer, Maintainer, or Owner).
+
+### Filters **(PREMIUM ONLY)**
+
+In GitLab Premium, you can add an LDAP user filter for group synchronization.
+Filters allow for complex logic without creating a special LDAP group.
+
+To sync GitLab group membership based on an LDAP filter:
+
+1. Open the **LDAP Synchronization** page for the GitLab group.
+1. Select **LDAP user filter** as the **Sync method**.
+1. Enter an LDAP user filter in the **LDAP user filter** field.
+
+The filter must comply with the
+syntax defined in [RFC 2254](https://tools.ietf.org/search/rfc2254).
 
 ## Administrator sync
 
@@ -140,30 +144,30 @@ group, as opposed to the full DN.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## Base where we can search for groups
-      ##
-      ##   Ex. ou=groups,dc=gitlab,dc=example
-      ##
-      ##
-      group_base: ou=groups,dc=example,dc=com
-
-      ##
-      ## The CN of a group containing GitLab administrators
-      ##
-      ##   Ex. administrators
-      ##
-      ##   Note: Not `cn=administrators` or the full DN
-      ##
-      ##
-      admin_group: my_admin_group
-
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## Base where we can search for groups
+     ##
+     ##   Ex. ou=groups,dc=gitlab,dc=example
+     ##
+     ##
+     group_base: ou=groups,dc=example,dc=com
+
+     ##
+     ## The CN of a group containing GitLab administrators
+     ##
+     ##   Ex. administrators
+     ##
+     ##   Note: Not `cn=administrators` or the full DN
+     ##
+     ##
+     admin_group: my_admin_group
+
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -171,26 +175,28 @@ group, as opposed to the full DN.
 
 1. Edit `/home/git/gitlab/config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            group_base: ou=groups,dc=example,dc=com
-            admin_group: my_admin_group
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           group_base: ou=groups,dc=example,dc=com
+           admin_group: my_admin_group
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
 ## Global group memberships lock
 
 "Lock memberships to LDAP synchronization" setting allows instance administrators
-to lock down user abilities to invite new members to a group. When enabled following happens:
+to lock down user abilities to invite new members to a group.
 
-1. Only administrator can manage memberships of any group including access levels.
-2. Users are not allowed to share project with other groups or invite members to a project created in a group.
+When enabled, the following applies:
 
+- Only administrator can manage memberships of any group including access levels.
+- Users are not allowed to share project with other groups or invite members to
+  a project created in a group.
 
 ## Adjusting LDAP user sync schedule
 
@@ -211,9 +217,9 @@ sync to run once every 12 hours at the top of the hour.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
-    ```
+   ```ruby
+   gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -221,11 +227,11 @@ sync to run once every 12 hours at the top of the hour.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    cron_jobs:
-      ldap_sync_worker_cron:
-        "0 */12 * * *"
-    ```
+   ```yaml
+   cron_jobs:
+     ldap_sync_worker_cron:
+       "0 */12 * * *"
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -252,9 +258,9 @@ sync to run once every 2 hours at the top of the hour.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
-    ```
+   ```ruby
+   gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * * *"
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -262,11 +268,11 @@ sync to run once every 2 hours at the top of the hour.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    cron_jobs:
-      ldap_group_sync_worker_cron:
-          "*/30 * * * *"
-    ```
+   ```yaml
+   cron_jobs:
+     ldap_group_sync_worker_cron:
+         "*/30 * * * *"
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -283,20 +289,20 @@ task.
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      ## snip...
-      ##
-      ## An array of CNs of groups containing users that should be considered external
-      ##
-      ##   Ex. ['interns', 'contractors']
-      ##
-      ##   Note: Not `cn=interns` or the full DN
-      ##
-      external_groups: ['interns', 'contractors']
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     ## snip...
+     ##
+     ## An array of CNs of groups containing users that should be considered external
+     ##
+     ##   Ex. ['interns', 'contractors']
+     ##
+     ##   Note: Not `cn=interns` or the full DN
+     ##
+     external_groups: ['interns', 'contractors']
+   EOS
+   ```
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
@@ -304,14 +310,14 @@ task.
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            external_groups: ['interns', 'contractors']
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           external_groups: ['interns', 'contractors']
+   ```
 
 1. [Restart GitLab][restart] for the changes to take effect.
 
@@ -330,10 +336,18 @@ administrative duties.
 
 ### Supported LDAP group types/attributes
 
-GitLab supports LDAP groups that use member attributes `member`, `submember`,
-`uniquemember`, `memberof` and `memberuid`. This means group sync supports, at
-least, LDAP groups with object class `groupOfNames`, `posixGroup`, and
-`groupOfUniqueName`. Other object classes should work fine as long as members
+GitLab supports LDAP groups that use member attributes:
+
+- `member`
+- `submember`
+- `uniquemember`
+- `memberof`
+- `memberuid`.
+
+This means group sync supports, at least, LDAP groups with object class:
+`groupOfNames`, `posixGroup`, and `groupOfUniqueName`.
+
+Other object classes should work fine as long as members
 are defined as one of the mentioned attributes. This also means GitLab supports
 Microsoft Active Directory, Apple Open Directory, Open LDAP, and 389 Server.
 Other LDAP servers should work, too.
@@ -341,11 +355,12 @@ Other LDAP servers should work, too.
 Active Directory also supports nested groups. Group sync will recursively
 resolve membership if `active_directory: true` is set in the configuration file.
 
-> **Note:** Nested group membership will only be resolved if the nested group
-  also falls within the configured `group_base`. For example, if GitLab sees a
-  nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but
-  the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group`
-  will be ignored.
+NOTE: **Note:**
+Nested group membership will only be resolved if the nested group
+also falls within the configured `group_base`. For example, if GitLab sees a
+nested group with DN `cn=nested_group,ou=special_groups,dc=example,dc=com` but
+the configured `group_base` is `ou=groups,dc=example,dc=com`, `cn=nested_group`
+will be ignored.
 
 ### Queries
 
@@ -400,7 +415,7 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server
 
 [^1]: In Active Directory, a user is marked as disabled/blocked if the user
       account control attribute (`userAccountControl:1.2.840.113556.1.4.803`)
-      has bit 2 set. See https://ctogonewild.com/2009/09/03/bitmask-searches-in-ldap/
+      has bit 2 set. See <https://ctogonewild.com/2009/09/03/bitmask-searches-in-ldap/>
       for more information.
 
 ### User DN has changed
@@ -420,10 +435,10 @@ things to check to debug the situation.
 - Ensure LDAP configuration has a `group_base` specified. This configuration is
   required for group sync to work properly.
 - Ensure the correct LDAP group link is added to the GitLab group. Check group
-  links by visiting the GitLab group, then **Settings dropdown -> LDAP groups**.
-- Check that the user has an LDAP identity
+  links by visiting the GitLab group, then **Settings dropdown > LDAP groups**.
+- Check that the user has an LDAP identity:
   1. Sign in to GitLab as an administrator user.
-  1. Navigate to **Admin area -> Users**.
+  1. Navigate to **Admin area > Users**.
   1. Search for the user
   1. Open the user, by clicking on their name. Do not click 'Edit'.
   1. Navigate to the **Identities** tab. There should be an LDAP identity with
@@ -434,68 +449,74 @@ Often, the best way to learn more about why group sync is behaving a certain
 way is to enable debug logging. There is verbose output that details every
 step of the sync.
 
-1. Start a Rails console
+1. Start a Rails console:
+
+   ```bash
+   # For Omnibus installations
+   sudo gitlab-rails console
 
-    ```bash
-    # For Omnibus installations
-    sudo gitlab-rails console
+   # For installations from source
+   sudo -u git -H bundle exec rails console production
+   ```
 
-    # For installations from source
-    sudo -u git -H bundle exec rails console production
-    ```
 1. Set the log level to debug (only for this session):
 
-    ```ruby
-    Rails.logger.level = Logger::DEBUG
-    ```
+   ```ruby
+   Rails.logger.level = Logger::DEBUG
+   ```
+
 1. Choose a GitLab group to test with. This group should have an LDAP group link
    already configured. If the output is `nil`, the group could not be found.
    If a bunch of group attributes are output, your group was found successfully.
 
-    ```ruby
-    group = Group.find_by(name: 'my_group')
+   ```ruby
+   group = Group.find_by(name: 'my_group')
+
+   # Output
+   => #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
+   ```
 
-    # Output
-    => #<Group:0x007fe825196558 id: 1234, name: "my_group"...>
-    ```
 1. Run a group sync for this particular group.
 
-    ```ruby
-    EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
-    ```
+   ```ruby
+   EE::Gitlab::Auth::LDAP::Sync::Group.execute_all_providers(group)
+   ```
+
 1. Look through the output of the sync. See [example log output](#example-log-output)
    below for more information about the output.
 1. If you still aren't able to see why the user isn't being added, query the
    LDAP group directly to see what members are listed. Still in the Rails console,
    run the following query:
 
-    ```ruby
-    adapter = Gitlab::Auth::LDAP::Adapter.new('ldapmain') # If `main` is the LDAP provider
-    ldap_group = EE::Gitlab::Auth::LDAP::Group.find_by_cn('group_cn_here', adapter)
+   ```ruby
+   adapter = Gitlab::Auth::LDAP::Adapter.new('ldapmain') # If `main` is the LDAP provider
+   ldap_group = EE::Gitlab::Auth::LDAP::Group.find_by_cn('group_cn_here', adapter)
+
+   # Output
+   => #<EE::Gitlab::Auth::LDAP::Group:0x007fcbdd0bb6d8
+   ```
 
-    # Output
-    => #<EE::Gitlab::Auth::LDAP::Group:0x007fcbdd0bb6d8
-    ```
 1. Query the LDAP group's member DNs and see if the user's DN is in the list.
    One of the DNs here should match the 'Identifier' from the LDAP identity
    checked earlier. If it doesn't, the user does not appear to be in the LDAP
    group.
 
-    ```ruby
-    ldap_group.member_dns
+   ```ruby
+   ldap_group.member_dns
+
+   # Output
+   => ["uid=john,ou=people,dc=example,dc=com", "uid=mary,ou=people,dc=example,dc=com"]
+   ```
 
-    # Output
-    => ["uid=john,ou=people,dc=example,dc=com", "uid=mary,ou=people,dc=example,dc=com"]
-    ```
 1. Some LDAP servers don't store members by DN. Rather, they use UIDs instead.
    If you didn't see results from the last query, try querying by UIDs instead.
 
-    ```ruby
-    ldap_group.member_uids
+   ```ruby
+   ldap_group.member_uids
 
-    # Output
-    => ['john','mary']
-    ```
+   # Output
+   => ['john','mary']
+   ```
 
 #### Example log output
 
@@ -532,8 +553,9 @@ and more DNs may be added, or existing entries modified, based on additional
 LDAP group lookups. The very last occurrence of this entry should indicate
 exactly which users GitLab believes should be added to the group.
 
-> **Note:** 10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer'
-  and 50 is 'Owner'
+NOTE: **Note:**
+10 is 'Guest', 20 is 'Reporter', 30 is 'Developer', 40 is 'Maintainer'
+and 50 is 'Owner'.
 
 ```bash
 Resolved 'my_group' group member access: {"uid=john0,ou=people,dc=example,dc=com"=>30,
diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md
index 2144f5753a8..186bf4c4825 100644
--- a/doc/administration/auth/ldap.md
+++ b/doc/administration/auth/ldap.md
@@ -1,30 +1,50 @@
+---
+type: reference
+---
+
 <!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. -->
 
 # LDAP
 
 GitLab integrates with LDAP to support user authentication.
-This integration works with most LDAP-compliant directory
-servers, including Microsoft Active Directory, Apple Open Directory, Open LDAP,
-and 389 Server. GitLab Enterprise Editions include enhanced integration,
+
+This integration works with most LDAP-compliant directory servers, including:
+
+- Microsoft Active Directory
+- Apple Open Directory
+- Open LDAP
+- 389 Server.
+
+GitLab Enterprise Editions (EE) include enhanced integration,
 including group membership syncing as well as multiple LDAP servers support.
 
-## GitLab EE
+For more details about EE-specific LDAP features, see the
+[LDAP Enterprise Edition documentation](ldap-ee.md).
+
+NOTE: **Note:**
+The information on this page is relevant for both GitLab CE and EE.
+
+## Overview
 
-The information on this page is relevant for both GitLab CE and EE. For more
-details about EE-specific LDAP features, see the
-[LDAP Enterprise Edition documentation](ldap-ee.md). **(STARTER ONLY)**
+[LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
+stands for **Lightweight Directory Access Protocol**, which is a standard
+application protocol for accessing and maintaining distributed directory
+information services over an Internet Protocol (IP) network.
 
 ## Security
 
-GitLab assumes that LDAP users are not able to change their LDAP 'mail', 'email'
-or 'userPrincipalName' attribute. An LDAP user who is allowed to change their
-email on the LDAP server can potentially
-[take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
-on your GitLab server.
+GitLab assumes that LDAP users:
+
+- Are not able to change their LDAP `mail`, `email`, or `userPrincipalName` attribute.
+  An LDAP user who is allowed to change their email on the LDAP server can potentially
+  [take over any account](#enabling-ldap-sign-in-for-existing-gitlab-users)
+  on your GitLab server.
+- Have unique email addresses, otherwise it is possible for LDAP users with the same
+  email address to share the same GitLab account.
 
 We recommend against using LDAP integration if your LDAP users are
-allowed to change their 'mail', 'email' or 'userPrincipalName'  attribute on
-the LDAP server.
+allowed to change their 'mail', 'email' or 'userPrincipalName' attribute on
+the LDAP server or share email addresses.
 
 ### User deletion
 
@@ -60,9 +80,12 @@ NOTE: **Note**:
 In GitLab Enterprise Edition Starter, you can configure multiple LDAP servers
 to connect to one GitLab server.
 
-For a complete guide on configuring LDAP with GitLab Community Edition, please check
-the admin guide [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md).
-For GitLab Enterprise Editions, see also [How to configure LDAP with GitLab EE](how_to_configure_ldap_gitlab_ee/index.md). **(STARTER ONLY)**
+For a complete guide on configuring LDAP with:
+
+- GitLab Community Edition, see
+  [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md).
+- Enterprise Editions, see
+  [How to configure LDAP with GitLab EE](how_to_configure_ldap_gitlab_ee/index.md). **(STARTER ONLY)**
 
 To enable LDAP integration you need to add your LDAP server settings in
 `/etc/gitlab/gitlab.rb` or `/home/git/gitlab/config/gitlab.yml` for Omnibus
@@ -380,7 +403,7 @@ production:
 Tip: If you want to limit access to the nested members of an Active Directory
 group, you can use the following syntax:
 
-```
+```text
 (memberOf:1.2.840.113556.1.4.1941:=CN=My Group,DC=Example,DC=com)
 ```
 
@@ -398,30 +421,30 @@ The `user_filter` DN can contain special characters. For example:
 
 - A comma:
 
-    ```
-    OU=GitLab, Inc,DC=gitlab,DC=com
-    ```
+  ```text
+  OU=GitLab, Inc,DC=gitlab,DC=com
+  ```
 
 - Open and close brackets:
 
-    ```
-    OU=Gitlab (Inc),DC=gitlab,DC=com
-    ```
+  ```text
+  OU=Gitlab (Inc),DC=gitlab,DC=com
+  ```
 
-    These characters must be escaped as documented in 
-    [RFC 4515](https://tools.ietf.org/search/rfc4515).
+  These characters must be escaped as documented in
+  [RFC 4515](https://tools.ietf.org/search/rfc4515).
 
 - Escape commas with `\2C`. For example:
 
-    ```
-    OU=GitLab\2C Inc,DC=gitlab,DC=com
-    ```
+  ```text
+  OU=GitLab\2C Inc,DC=gitlab,DC=com
+  ```
 
 - Escape open and close brackets with `\28` and `\29`, respectively. For example:
 
-    ```
-    OU=Gitlab \28Inc\29,DC=gitlab,DC=com
-    ```
+  ```text
+  OU=Gitlab \28Inc\29,DC=gitlab,DC=com
+  ```
 
 ## Enabling LDAP sign-in for existing GitLab users
 
@@ -445,13 +468,13 @@ the configuration option `lowercase_usernames`. By default, this configuration o
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      # snip...
-      lowercase_usernames: true
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     # snip...
+     lowercase_usernames: true
+   EOS
+   ```
 
 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
@@ -459,14 +482,14 @@ the configuration option `lowercase_usernames`. By default, this configuration o
 
 1. Edit `config/gitlab.yaml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            lowercase_usernames: true
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           lowercase_usernames: true
+   ```
 
 1. [Restart GitLab](../restart_gitlab.md#installations-from-source) for the changes to take effect.
 
@@ -494,13 +517,20 @@ be mandatory and clients cannot be authenticated with the TLS protocol.
 
 ## Troubleshooting
 
+If a user account is blocked or unblocked due to the LDAP configuration, a
+message will be logged to `application.log`.
+
+If there is an unexpected error during an LDAP lookup (configuration error,
+timeout), the login is rejected and a message will be logged to
+`production.log`.
+
 ### Debug LDAP user filter with ldapsearch
 
-This example uses ldapsearch and assumes you are using ActiveDirectory. The
+This example uses `ldapsearch` and assumes you are using ActiveDirectory. The
 following query returns the login names of the users that will be allowed to
 log in to GitLab if you configure your own user_filter.
 
-```
+```sh
 ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$base" "$user_filter" sAMAccountName
 ```
 
@@ -519,26 +549,17 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt  -b "$ba
 - Run the following check command to make sure that the LDAP settings are
   correct and GitLab can see your users:
 
-    ```bash
-    # For Omnibus installations
-    sudo gitlab-rake gitlab:ldap:check
+  ```bash
+  # For Omnibus installations
+  sudo gitlab-rake gitlab:ldap:check
 
-    # For installations from source
-    sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
-    ```
+  # For installations from source
+  sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production
+  ```
 
-### Connection Refused
+### Connection refused
 
 If you are getting 'Connection Refused' errors when trying to connect to the
 LDAP server please double-check the LDAP `port` and `encryption` settings used by
 GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR
 `encryption: 'simple_tls'` and `port: 636`.
-
-### Troubleshooting
-
-If a user account is blocked or unblocked due to the LDAP configuration, a
-message will be logged to `application.log`.
-
-If there is an unexpected error during an LDAP lookup (configuration error,
-timeout), the login is rejected and a message will be logged to
-`production.log`.
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index 6e48add6930..3445f916ef4 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # OpenID Connect OmniAuth provider
 
 GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider.
@@ -5,101 +9,103 @@ GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0
 To enable the OpenID Connect OmniAuth provider, you must register your application with an OpenID Connect provider.
 The OpenID Connect will provide you with a client details and secret for you to use.
 
-1.  On your GitLab server, open the configuration file.
-
-    For Omnibus GitLab:
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    For installations from source:
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-    See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
-
-1.  Add the provider configuration.
-
-    For Omnibus GitLab:
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      { 'name' => 'openid_connect',
-        'label' => '<your_oidc_label>',
-        'args' => {
-          "name' => 'openid_connect',
-          'scope' => ['openid','profile'],
-          'response_type' => 'code',
-          'issuer' => '<your_oidc_url>',
-          'discovery' => true,
-          'client_auth_method' => 'query',
-          'uid_field' => '<uid_field>',
-          'client_options' => {
-            'identifier' => '<your_oidc_client_id>',
-            'secret' => '<your_oidc_client_secret>',
-            'redirect_uri' => '<your_gitlab_url>/users/auth/openid_connect/callback'
-          }
-        }
-      }
-    ]
-    ```
-
-    For installation from source:
-
-    ```yaml
-      - { name: 'openid_connect',
-          label: '<your_oidc_label>',
-          args: {
-            name: 'openid_connect',
-            scope: ['openid','profile'],
-            response_type: 'code',
-            issuer: '<your_oidc_url>',
-            discovery: true,
-            client_auth_method: 'query',
-            uid_field: '<uid_field>',
-            client_options: {
-              identifier: '<your_oidc_client_id>',
-              secret: '<your_oidc_client_secret>',
-              redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
-            }
-          }
-        }
-    ```
-
-    > **Note:**
-    >
-    > - For more information on each configuration option refer to
-        the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) and
-        the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
+1. On your GitLab server, open the configuration file.
+
+   For Omnibus GitLab:
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+   See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration) for initial settings.
+
+1. Add the provider configuration.
+
+   For Omnibus GitLab:
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     { 'name' => 'openid_connect',
+       'label' => '<your_oidc_label>',
+       'args' => {
+         "name' => 'openid_connect',
+         'scope' => ['openid','profile'],
+         'response_type' => 'code',
+         'issuer' => '<your_oidc_url>',
+         'discovery' => true,
+         'client_auth_method' => 'query',
+         'uid_field' => '<uid_field>',
+         'client_options' => {
+           'identifier' => '<your_oidc_client_id>',
+           'secret' => '<your_oidc_client_secret>',
+           'redirect_uri' => '<your_gitlab_url>/users/auth/openid_connect/callback'
+         }
+       }
+     }
+   ]
+   ```
+
+   For installation from source:
+
+   ```yaml
+     - { name: 'openid_connect',
+         label: '<your_oidc_label>',
+         args: {
+           name: 'openid_connect',
+           scope: ['openid','profile'],
+           response_type: 'code',
+           issuer: '<your_oidc_url>',
+           discovery: true,
+           client_auth_method: 'query',
+           uid_field: '<uid_field>',
+           client_options: {
+             identifier: '<your_oidc_client_id>',
+             secret: '<your_oidc_client_secret>',
+             redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'
+           }
+         }
+       }
+   ```
+
+   NOTE: **Note:**
+   For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage)
+   and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
 
 1. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide:
-    - `<your_oidc_label>` is the label that will be displayed on the login page.
-    - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
-      If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
-    - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
-    - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
-      If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
-    - `client_options` are the OpenID Connect client-specific options. Specifically:
-
-      - `identifier` is the client identifier as configured in the OpenID Connect service provider.
-      - `secret` is the client secret as configured in the OpenID Connect service provider.
-      - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
-      - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
-
-      The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
-
-        - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
-        - `token_endpoint` is the URL to the endpoint that provides Access Token.
-        - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
-        - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
-
-1.  Save the configuration file.
-1.  [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
-    for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
+   - `<your_oidc_label>` is the label that will be displayed on the login page.
+   - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
+     If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
+   - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
+   - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider.
+     - Supported values are:
+       - `basic` - HTTP Basic Authentication
+       - `jwt_bearer` - JWT based authentication (private key and client secret signing)
+       - `mtls` - Mutual TLS or X.509 certificate validation
+       - Any other value will POST the client id and secret in the request body
+     - If not specified, defaults to `basic`.
+   - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
+     If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
+   - `client_options` are the OpenID Connect client-specific options. Specifically:
+     - `identifier` is the client identifier as configured in the OpenID Connect service provider.
+     - `secret` is the client secret as configured in the OpenID Connect service provider.
+     - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
+     - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
+     - The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
+       - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
+       - `token_endpoint` is the URL to the endpoint that provides Access Token.
+       - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
+       - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
+
+1. Save the configuration file.
+1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
+   for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
 
 On the sign in page, there should now be an OpenID Connect icon below the regular sign in form.
 Click the icon to begin the authentication process. The OpenID Connect provider will ask the user to
@@ -139,7 +145,7 @@ for more details:
  }
 ```
 
-### Troubleshooting
+## Troubleshooting
 
 If you're having trouble, here are some tips:
 
@@ -155,9 +161,9 @@ If you're having trouble, here are some tips:
    `https://accounts.google.com/.well-known/openid-configuration`.
 
 1. The OpenID Connect client uses HTTP Basic Authentication to send the
-   OAuth2 access token. For example, if you are seeing 401 errors upon
-   retrieving the `userinfo` endpoint, you may want to check your OpenID
-   Web server configuration. For example, for
+   OAuth2 access token if `client_auth_method` is not defined or if set to `basic`.
+   If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may
+   want to check your OpenID Web server configuration. For example, for
    [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you
    may need to [add a configuration parameter to
    Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778).
diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md
index aa4e1b0d2e0..5524c3ba092 100644
--- a/doc/administration/auth/okta.md
+++ b/doc/administration/auth/okta.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Okta SSO provider
 
 Okta is a [Single Sign-on provider](https://www.okta.com/products/single-sign-on/) that can be used to authenticate
@@ -16,7 +20,7 @@ The following documentation enables Okta as a SAML provider.
 1. Next, you'll need the to fill in the SAML general config. Here's an example
    image.
 
-    ![Okta admin panel view](img/okta_admin_panel.png)
+   ![Okta admin panel view](img/okta_admin_panel.png)
 
 1. The last part of the configuration is the feedback section where you can
    just say you're a customer and creating an app for internal use.
@@ -24,7 +28,7 @@ The following documentation enables Okta as a SAML provider.
    profile. Click on the SAML 2.0 config instructions button which should
    look like the following:
 
-    ![Okta SAML settings](img/okta_saml_settings.png)
+   ![Okta SAML settings](img/okta_saml_settings.png)
 
 1. On the screen that comes up take note of the
    **Identity Provider Single Sign-On URL** which you'll use for the
@@ -38,112 +42,112 @@ Now that the Okta app is configured, it's time to enable it in GitLab.
 
 ## Configure GitLab
 
-1.  On your GitLab server, open the configuration file:
-
-    **For Omnibus GitLab installations**
-
-    ```sh
-    sudo editor /etc/gitlab/gitlab.rb
-    ```
-
-    **For installations from source**
-
-    ```sh
-    cd /home/git/gitlab
-    sudo -u git -H editor config/gitlab.yml
-    ```
-
-1.  See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
-    for initial settings.
-
-1.  To allow your users to use Okta to sign up without having to manually create
-    an account first, don't forget to add the following values to your
-    configuration:
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
-    gitlab_rails['omniauth_block_auto_created_users'] = false
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    allow_single_sign_on: ["saml"]
-    block_auto_created_users: false
-    ```
-
-1.  You can also automatically link Okta users with existing GitLab users if
-    their email addresses match by adding the following setting:
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_auto_link_saml_user'] = true
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    auto_link_saml_user: true
-    ```
-
-1.  Add the provider configuration.
-
-      >**Notes:**
-      >
-      >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
-         of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
-         installation to generate the correct value).
-      >   
-      >- To get the `idp_cert_fingerprint` fingerprint, first download the
-         certificate from the Okta app you registered and then run:
-         `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert`
-         with the location of your certificate.
-      >
-      >- Change the value of `idp_sso_target_url`, with the value of the
-         **Identity Provider Single Sign-On URL** from the step when you
-         configured the Okta app.
-      >     
-      >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab
-         to the IdP.
-      >     
-      >- Leave `name_identifier_format` as-is.
-
-    **For Omnibus GitLab installations**
-
-    ```ruby
-    gitlab_rails['omniauth_providers'] = [
-      {
-        name: 'saml',
-        args: {
-                 assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-                 idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-                 idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
-                 issuer: 'https://gitlab.example.com',
-                 name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
-               },
-        label: 'Okta' # optional label for SAML login button, defaults to "Saml"
-      }
-    ]
-    ```
-
-    **For installations from source**
-
-    ```yaml
-    - {
-        name: 'saml',
-        args: {
-               assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
-               idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
-               idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
-               issuer: 'https://gitlab.example.com',
-               name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
-             },
-        label: 'Okta' # optional label for SAML login button, defaults to "Saml"
-      }
-    ```
+1. On your GitLab server, open the configuration file:
+
+   **For Omnibus GitLab installations**
+
+   ```sh
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   **For installations from source**
+
+   ```sh
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. See [Initial OmniAuth Configuration](../../integration/omniauth.md#initial-omniauth-configuration)
+   for initial settings.
+
+1. To allow your users to use Okta to sign up without having to manually create
+   an account first, don't forget to add the following values to your
+   configuration:
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
+   gitlab_rails['omniauth_block_auto_created_users'] = false
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   allow_single_sign_on: ["saml"]
+   block_auto_created_users: false
+   ```
+
+1. You can also automatically link Okta users with existing GitLab users if
+   their email addresses match by adding the following setting:
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_auto_link_saml_user'] = true
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   auto_link_saml_user: true
+   ```
+
+1. Add the provider configuration.
+
+   >**Notes:**
+   >
+   >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint
+      of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab
+      installation to generate the correct value).
+   >
+   >- To get the `idp_cert_fingerprint` fingerprint, first download the
+      certificate from the Okta app you registered and then run:
+      `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert`
+      with the location of your certificate.
+   >
+   >- Change the value of `idp_sso_target_url`, with the value of the
+      **Identity Provider Single Sign-On URL** from the step when you
+      configured the Okta app.
+   >
+   >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab
+      to the IdP.
+   >
+   >- Leave `name_identifier_format` as-is.
+
+   **For Omnibus GitLab installations**
+
+   ```ruby
+   gitlab_rails['omniauth_providers'] = [
+     {
+       name: 'saml',
+       args: {
+                assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+                idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+                idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
+                issuer: 'https://gitlab.example.com',
+                name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+              },
+       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
+     }
+   ]
+   ```
+
+   **For installations from source**
+
+   ```yaml
+   - {
+       name: 'saml',
+       args: {
+              assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
+              idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8',
+              idp_sso_target_url: 'https://gitlab.oktapreview.com/app/gitlabdev773716_gitlabsaml_1/exk8odl81tBrjpD4B0h7/sso/saml',
+              issuer: 'https://gitlab.example.com',
+              name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'
+            },
+       label: 'Okta' # optional label for SAML login button, defaults to "Saml"
+     }
+   ```
 
 1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart](../restart_gitlab.md#installations-from-source) GitLab for Omnibus and installations
    from source respectively for the changes to take effect.
@@ -157,3 +161,15 @@ Make sure the groups exist and are assigned to the Okta app.
 
 You can take a look of the [SAML documentation](../../integration/saml.md#marking-users-as-external-based-on-saml-groups) on external groups since
 it works the same.
+
+<!-- ## 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. -->
diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md
index a0d4e9ef3b5..4f236d1afb8 100644
--- a/doc/administration/auth/smartcard.md
+++ b/doc/administration/auth/smartcard.md
@@ -1,3 +1,7 @@
+---
+type: reference
+---
+
 # Smartcard authentication **(PREMIUM ONLY)**
 
 GitLab supports authentication using smartcards.
@@ -22,7 +26,7 @@ To use a smartcard with an X.509 certificate to authenticate against a local
 database with GitLab, `CN` and `emailAddress` must be defined in the
 certificate. For example:
 
-```
+```text
 Certificate:
     Data:
         Version: 1 (0x0)
@@ -56,11 +60,11 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['smartcard_enabled'] = true
-    gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
-    gitlab_rails['smartcard_client_certificate_required_port'] = 3444
-    ```
+   ```ruby
+   gitlab_rails['smartcard_enabled'] = true
+   gitlab_rails['smartcard_ca_file'] = "/etc/ssl/certs/CA.pem"
+   gitlab_rails['smartcard_client_certificate_required_port'] = 3444
+   ```
 
 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
@@ -154,15 +158,15 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['ldap_servers'] = YAML.load <<-EOS
-    main:
-      # snip...
-      # Enable smartcard authentication against the LDAP server. Valid values
-      # are "false", "optional", and "required".
-      smartcard_auth: optional
-    EOS
-    ```
+   ```ruby
+   gitlab_rails['ldap_servers'] = YAML.load <<-EOS
+   main:
+     # snip...
+     # Enable smartcard authentication against the LDAP server. Valid values
+     # are "false", "optional", and "required".
+     smartcard_auth: optional
+   EOS
+   ```
 
 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
@@ -171,16 +175,16 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    production:
-      ldap:
-        servers:
-          main:
-            # snip...
-            # Enable smartcard authentication against the LDAP server. Valid values
-            # are "false", "optional", and "required".
-            smartcard_auth: optional
-    ```
+   ```yaml
+   production:
+     ldap:
+       servers:
+         main:
+           # snip...
+           # Enable smartcard authentication against the LDAP server. Valid values
+           # are "false", "optional", and "required".
+           smartcard_auth: optional
+   ```
 
 1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
    GitLab for the changes to take effect.
@@ -191,9 +195,9 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `/etc/gitlab/gitlab.rb`:
 
-    ```ruby
-    gitlab_rails['smartcard_required_for_git_access'] = true
-    ```
+   ```ruby
+   gitlab_rails['smartcard_required_for_git_access'] = true
+   ```
 
 1. Save the file and [reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure)
    GitLab for the changes to take effect.
@@ -202,13 +206,25 @@ attribute. As a prerequisite, you must use an LDAP server that:
 
 1. Edit `config/gitlab.yml`:
 
-    ```yaml
-    ## Smartcard authentication settings
-    smartcard:
-      # snip...
-      # Browser session with smartcard sign-in is required for Git access
-      required_for_git_access: true
-    ```
+   ```yaml
+   ## Smartcard authentication settings
+   smartcard:
+     # snip...
+     # Browser session with smartcard sign-in is required for Git access
+     required_for_git_access: true
+   ```
 
 1. Save the file and [restart](../restart_gitlab.md#installations-from-source)
    GitLab for the changes to take effect.
+
+<!-- ## 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. -->