From a02ec8d27fcc0c996c8c29032ad167bccf234406 Mon Sep 17 00:00:00 2001
From: Stan Hu <stanhu@gmail.com>
Date: Thu, 1 Feb 2024 21:24:23 -0800
Subject: [PATCH] Move mutual TLS config docs for Webhooks to right location

Previously the TLS config was inserted into the section relating to
filtering outbound requests. It's probably better to put this in the
actual Webhook documentation.
---
 doc/security/webhooks.md                  | 74 ---------------------
 doc/user/project/integrations/webhooks.md | 81 +++++++++++++++++++++++
 2 files changed, 81 insertions(+), 74 deletions(-)

diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md
index 59452675216f1..278272a384b3e 100644
--- a/doc/security/webhooks.md
+++ b/doc/security/webhooks.md
@@ -147,80 +147,6 @@ example.com;gitlab.example.com
 example.com:8080
 ```
 
-## Configure webhooks to support mutual TLS
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
-
-You can configure webhooks to support mutual TLS by configuring a client
-certificate in PEM format. This certificate is set globally and
-presented to the server during a TLS handshake. The certificate can also
-be protected with a PEM passphrase.
-
-To configure the certificate, follow the instructions:
-
-::Tabs
-
-:::TabTitle Linux package (Omnibus)
-
-1. Edit `/etc/gitlab/gitlab.rb`:
-
-   ```ruby
-   gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
-   gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
-   ```
-
-1. Save the file and reconfigure GitLab:
-
-   ```shell
-   sudo gitlab-ctl reconfigure
-   ```
-
-:::TabTitle Docker
-
-1. Edit `docker-compose.yml`:
-
-   ```yaml
-   version: "3.6"
-   services:
-     gitlab:
-       image: 'gitlab/gitlab-ee:latest'
-       restart: always
-       hostname: 'gitlab.example.com'
-       environment:
-         GITLAB_OMNIBUS_CONFIG: |
-            gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
-            gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
-   ```
-
-1. Save the file and restart GitLab:
-
-   ```shell
-   docker compose up -d
-   ```
-
-:::TabTitle Self-compiled (source)
-
-1. Edit `/home/git/gitlab/config/gitlab.yml`:
-
-   ```yaml
-   production: &base
-     http_client:
-       tls_client_cert_file: '<PATH TO CLIENT PEM FILE>'
-       tls_client_cert_password: '<OPTIONAL PASSWORD>'
-   ```
-
-1. Save the file and restart GitLab:
-
-   ```shell
-   # For systems running systemd
-   sudo systemctl restart gitlab.target
-
-   # For systems running SysV init
-   sudo service gitlab restart
-   ```
-
-::EndTabs
-
 ## Troubleshooting
 
 When filtering outbound requests, you might encounter the following issues.
diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md
index 7ff9f05d0a926..314e0ec652908 100644
--- a/doc/user/project/integrations/webhooks.md
+++ b/doc/user/project/integrations/webhooks.md
@@ -329,6 +329,87 @@ For a safer development environment, you can use the [GitLab Development Kit (GD
 
 You can [review recently triggered webhook payloads](#troubleshooting) in GitLab settings. For each webhook event, a detail page exists with information about the data GitLab sends and receives from the webhook endpoint.
 
+## Configure webhooks to support mutual TLS
+
+DETAILS:
+**Offering:** self-managed
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27450) in GitLab 16.9.
+
+Prerequisites:
+
+- You must be a GitLab administrator.
+
+You can configure webhooks to support mutual TLS by configuring a client
+certificate in PEM format. This certificate is set globally and
+presented to the server during a TLS handshake. The certificate can also
+be protected with a PEM passphrase.
+
+To configure the certificate, follow the instructions below.
+
+::Tabs
+
+:::TabTitle Linux package (Omnibus)
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
+   gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
+   ```
+
+1. Save the file and reconfigure GitLab:
+
+   ```shell
+   sudo gitlab-ctl reconfigure
+   ```
+
+:::TabTitle Docker
+
+1. Edit `docker-compose.yml`:
+
+   ```yaml
+   version: "3.6"
+   services:
+     gitlab:
+       image: 'gitlab/gitlab-ee:latest'
+       restart: always
+       hostname: 'gitlab.example.com'
+       environment:
+         GITLAB_OMNIBUS_CONFIG: |
+            gitlab_rails['http_client']['tls_client_cert_file'] = '<PATH TO CLIENT PEM FILE>'
+            gitlab_rails['http_client']['tls_client_cert_password'] = '<OPTIONAL PASSWORD>'
+   ```
+
+1. Save the file and restart GitLab:
+
+   ```shell
+   docker compose up -d
+   ```
+
+:::TabTitle Self-compiled (source)
+
+1. Edit `/home/git/gitlab/config/gitlab.yml`:
+
+   ```yaml
+   production: &base
+     http_client:
+       tls_client_cert_file: '<PATH TO CLIENT PEM FILE>'
+       tls_client_cert_password: '<OPTIONAL PASSWORD>'
+   ```
+
+1. Save the file and restart GitLab:
+
+   ```shell
+   # For systems running systemd
+   sudo systemctl restart gitlab.target
+
+   # For systems running SysV init
+   sudo service gitlab restart
+   ```
+
+::EndTabs
+
 ## Related topics
 
 - [Project hooks API](../../../api/projects.md#hooks)
-- 
GitLab