GitLab Pages feature documentation is confusing

My configuration: Self-hosted GitLab 12.0.3-ee (1b1872f9d93)

Documentation Issue

The documentation about GitLab Pages is quite confusing when it comes to set this up on our own instance (self-managed). I'm talking about these 2 pages mainly:

• https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/index.html
• https://docs.gitlab.com/ee/administration/pages/index.html

One major confusion comes from the fact that the custom domain configuration is not available unless the parameter gitlab_pages['external_http'] is configured in gitlab.rb, but this is not specified anywhere (I found this during a random search on google...). I just found an issue about that but no one replied within 2 months: https://gitlab.com/gitlab-org/gitlab-ee/issues/11442

So then I tried to follow the steps described in https://docs.gitlab.com/ee/administration/pages/index.html

• In the Custom Domain section, an URL scheme is given but without further explanation about what URL means what.
  • I assumed that 'http://page.example.io' was the url of our GitLab Pages, served by our Gitlab instance, and that 'http://domain.com' that the custom domain that we want to use to publish our GitLab pages on the public side, but I'm not quite sure of this. The problem is that this 'http://domain.com' is not referenced any further in the documentation so we don't know what to do with that domain. And it's the same in the Custom domains with TLS support
• I also figured out that some chapters are present today (2019.07.18) but are about a future release of GitLab (planned for 2019.07.22): https://docs.gitlab.com/ee/administration/pages/index.html#lets-encrypt-integration => this can be confusing if we don't know exactly which version we are running, since "Introduced in GitLab 12.1." means something in the past AFAIK...

Problem Summary

In the end, my problem is that I was able to setup a GitLab page in about 30 min using GitLab-CI, then it took me approx 4h to make it available on a public website, and it's now been 2 days that I try to activate TLS and to set-up a customer domain but I'm thinking that my understanding of "custom" domain may not be the same than yours...

Extra questions regarding my need

I think that my use-case has nothing out of ordinary but somehow it seems very complicated to set up despite the interesting available feature. I'll create an issue somewhere else about my problem but I would appreciate that the documentation improves to explain:

• What is a custom domain and what should be our interest in using it?
  • Is it to redirect the GitLab Pages auto-generated URL: https://.// into a more user friendly URL? If so that's exactly what I'm trying to do but I just can't with the current status of the documentation.
  • If it's about something else, I would appreciate some explanation

My use-case description

I'll also describe my use-case so that I can hopefully have some feedback from your side about it, if it's really out of the ordinary or not:

• my GitLab instance is hosted on our own (rented) server and is available on gitlab.mycompany.com
• my company owns the domain mycompany.com
• I am admin of the registrar so I can do what I want except that mycompany.com is redirecting to my company's website so I can't change it. But we also own mycompany.io, so I intend to have a redirection from mycompany.io or documentation.mycompany.io to the GitLab Pages I generated.
• On my GitLab instance, I have a project within a sub-group within a group, and I would rather not to change this structure.
• I configured gitlab.rb with the following:
  • pages_external_url "http://documentation.mycompany.com/"
• Therefore, when I generate the GitLab pages on this project, it generates it at the following URL: http://<group-name>.documentation.mycompany.com/<sub-group-name>/<project-name>
  • Side-note: The fact that the same domain is used for the Gitlab instance, the company's website and all internal company network dependencies causes me some troubles accessing the generated GitLab pages inside my company's network but I figured it out...
• Now comes my problem: how can I use another URL to redirect to this long-and-not-user-friendly-at-all URL auto-generated by GitLab ?

=> It seems I have to configure both gitlab.rb and my Project Pages settings by adding a new domain, but despite the dozens of configuration trial I did based on the above-mentioned Gitlab documentation pages, I can't find a correct configuration so I would really appreciate some help.

Just a final note to mention that globally I love GitLab and the documentation is quite good but I was expecting to setup my GitLab page easily and it turns out I'm stuck on the apparently most simple part of the topic but in the end the most complex to understand and configure.