Skip to content

GitLab Pages

Support for GitLab Pages is enabled by default via the *.pages.<prefix>.glhc.nl domain name, which is automatically added to the DNS zone and included in the HTTPS certificate. The Pages daemon runs on the gitlab-rails nodes in all cases.

Access control for GitLab pages is force-enabled for the entire cluster. Users can make their pages publicly readably using the visibility configuration for pages on their project, which bypasses the login flow on that project.

The following relevant ansible variables are available:

Name Default Description
pages_external_url "" The URL on which pages is available, including "https://"

Using custom domains with GitLab Pages

Because of the requirement for additional manual work, custom domains for GitLab pages is currently not enabled by default. If you need to enable this feature, you must first ensure the following requirements are met:

  • You have configured GitLab pages without custom domains as described in the section above.
  • You have a TLS certificate and private key for your pages domain, and the wildcard variant of that pages domain.
  • You have informed the customer about the additional security risks that may arise from allowing users to use custom domains on a GitLab instance.

The TLS certificate requirement is also applicable if you are using the default pages.<prefix>.glhc.nl domain. TLS certificate for pages cannot be automated at this point in time, there is no point in requesting the certificate in AWS ACM.

When enabling custom domains, the following changes will be made, which may result in temporary downtime:

  • The ALB will stop handling Pages requests, and any lingering requests will be sent to the Rails nodes instead, resulting in 404 errors.
  • A new NLB will be added speficially for handling Pages requests, and the relevant DNS changes will be made for that.
  • TLS offloading of Pages requests is disabled and the toolkit will no longer request a TLS certificate for the domain.
  • The Pages feature will be unavailable between running Terraform and the Ansible playbooks being completed.

To configure custom domains, you must make the following changes to your solution configuration:

  • In Terraform, you must set pages_enable_custom_domains to true on the aws/cluster module. This will automatically set a variable with the same name in Ansible as well.
  • You must place a TLS certificate and private key in ansible/files/tls/pages.{crt,key} in your solution folder, or override the variables pages_ssl_{cert,key}_file to point to an alternative location on disk.

Afterwards, you can (have the customer) configure the additional preferences for custom domains in the GitLab Admin section of the webinterface, such as the Let's Encrypt contact email address, and setting if domain validation is required. Please note that non-authenticated users cannot access pages content when the visibility settings of a project is not set to public, even when the content is being served on a custom domain.