Merge branch 'patch-52' into 'master'

Improve pages custom CA docs

See merge request gitlab-org/gitlab!22513

doc/administration/pages/index.md

@@ -342,16 +342,28 @@ pages:
 
 1. [Reconfigure GitLab][reconfigure] for the changes to take effect.
 
-### Using a custom Certificate Authority (CA) with Access Control
+### Using a custom Certificate Authority (CA)
 
-When using certificates issued by a custom CA, Access Control on GitLab Pages may fail to work if the custom CA is not recognized.
+When using certificates issued by a custom CA, [Access Control](../../user/project/pages/pages_access_control.md#gitlab-pages-access-control) and
+the [online view of HTML job artifacts](../../user/project/pipelines/job_artifacts.md#browsing-artifacts)
+will fail to work if the custom CA is not recognized.
 
 This usually results in this error:
 `Post /oauth/token: x509: certificate signed by unknown authority`.
 
-For GitLab Pages Access Control with TLS/SSL certs issued by an internal or custom CA:
+For installation from source this can be fixed by installing the custom Certificate
+Authority (CA) in the system certificate store.
 
-1. Copy the certificate bundle to `/opt/gitlab/embedded/ssl/certs/` in `.pem` format.
+For Omnibus, normally this would be fixed by [installing a custom CA in GitLab Omnibus](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates)
+but a [bug](https://gitlab.com/gitlab-org/gitlab/issues/25411) is currently preventing
+that method from working. Use the following workaround:
+
+1. Append your GitLab server TLS/SSL certficate to `/opt/gitlab/embedded/ssl/certs/cacert.pem` where `gitlab-domain-example.com` is your GitLab application URL
+
+    ```bash
+    printf "\ngitlab-domain-example.com\n===========================\n" | sudo tee --append /opt/gitlab/embedded/ssl/certs/cacert.pem
+    echo -n | openssl s_client -connect gitlab-domain-example.com:443  | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' | sudo tee --append /opt/gitlab/embedded/ssl/certs/cacert.pem
+    ```
 
 1. [Restart](../restart_gitlab.md) the GitLab Pages Daemon. For GitLab Omnibus instances:
 
@@ -359,6 +371,9 @@ For GitLab Pages Access Control with TLS/SSL certs issued by an internal or cust
     sudo gitlab-ctl restart gitlab-pages
     ```
 
+CAUTION: **Caution:**
+Some GitLab Omnibus upgrades will revert this workaround and you'll need to apply it again.
+
 ## Activate verbose logging for daemon
 
 Verbose logging was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/2533) in