GitLab Pages

You can use GitLab Pages to host static web pages for your existing Git repositories. You can also find a complete list of all functions in the official GitLab documentation at https://docs.gitlab.com/ee/administration/pages/



Prerequisites

  • GitLab 15 CE or EE
  • Dedicated GitLab Pages domain (e.g. pages.company.com)
  • Wildcard SSL certificate for the GitLab Pages domain
  • SSH/FTP/SFTP access (optional for SSL)



Activate GitLab Pages

The following steps are required for the configuration and initial setup of GitLab Pages:


Wildcard DNS entry

To use the GitLab Pages integration, a wildcard DNS entry must be created for the GitLab Pages module. The DNS entry must not be a subdomain of the existing instance.

RR-Type Host Value
A pages IPv4 address GitLab Server
AAAA pages IPv6 address GitLab Server
A *.pages IPv4 address GitLab Server
AAAA *.pages IPv6 address GitLab Server


A dedicated domain is required for the GitLab Pages integration. The domain must not be a subdomain of the existing GitLab instance. If your GitLab instance is accessible at git.company.com, the domain pages.company.com would be possible. Use on the subdomain pages.git.company.com is not permitted.


Place wildcard SSL certificate in the GitLab server instance

Use our Sectigo Essential SSL certificate, for example, for the wildcard SSL certificate. Alternatively, you can also issue a free wildcard SSL certificate from Let's Encrypt via our customer center. Please note that the free certificate is only valid for 3 months and must be renewed manually before it expires.

See also: https://www.creoline.com/de/certificates


Customize GitLab configuration

Once the necessary DNS entries have been entered and the required SSL certificate has been issued, you can start the configuration in GitLab.

To set up GitLab Pages, log in to the creoline Customer Center and navigate to the GitLab server for which you want to set up GitLab Pages. Select the Configuration files tab and then click Edit.

Customize the configuration as follows, the corresponding number of the line in the configuration file can also be found in the following image:


You can also use Ctrl + F (Windows) or Command + F (MacOs) to search for a specific term or similar within the configuration file for faster navigation when editing large configuration files.


Enter the desired new GitLab URL in the pages_external_url area.

Example:

pages_external_url "https://pages.company.com"


To ensure that the function is activated and works properly with the web server used, it is necessary to also add or activate the following points in the configuration file:

# Activate GitLab Pages module
gitlab_pages['enable'] = true

# Deploy GitLab Pages module via nginx
pages_nginx['enable'] = true

# Automatically redirect GitLab Pages module to https://
pages_nginx['redirect_http_to_https'] = true


The configuration of pages_nginx['ssl_certificate'] and pages_nginx['ssl_certificate'] is only required if you deviate from the naming convention. GitLab expects the necessary certificate files to be provided according to the following scheme:

type path example
Server certificate (incl. chain) /etc/gitlab/ssl/[WILDCARD_DOMAIN].crt /etc/gitlab/ssl/pages.company.com.crt
Private key /etc/gitlab/ssl/[WILDCARD_DOMAIN].key /etc/gitlab/ssl/pages.company.com.key


Then store the two certificate components in the directory /etc/gitlab/ssl via SSH or FTP/SFTP as described above.


Then enter a short message in the Change message area explaining why the GitLab URL was changed and save the changes using the Save changes button.


Saving the configuration automatically triggers the deployment of the configuration and the subsequent restart of GitLab. Inform active users about the planned action in advance.

The deployment status can be found on the Deployments tab.

After the deployment has been successfully completed, you can access the general settings of the GitLab Pages integration via the GitLab web interface.


To do this, navigate to the menu item: Admin → Settings → Preferences → Pages

GitLab Pages - Einstellungen




Activate GitLab Pages integration for an existing repository

Navigate to the desired repository and call up the menu item Settings → Pages. From here, you can customize the pipeline configuration via gitlab-ci.yml to activate the GitLab Page.




GitLab Pages Custom Domains

In addition to the basic GitLab Pages module, you can also use custom domains for repositories that differ from the previously created GitLab Pages domain. For the integration of custom domains, an additional IPv4 and IPv6 address is required.


Additional IPv4 addresses can be booked directly via our live chat or via our ticket system. Current prices for additional IP addresses can be found in the article Price list for additional and special services.


After the additional IP addresses have been stored on the GitLab server, each desired custom domain must be configured for use.


DNS settings for GitLab Pages custom domains:

RR-Type Host Value
A custom-domain.com Additional IPv4 address
AAAA custom-domain.com Additional IPv6 address


There are no technical requirements for the host share for custom domains. You can use the primary domain as well as any subdomain. Once you have created the required DNS entries, the custom domain can be set in the repository settings. GitLab automatically attempts to apply for a Let's Encrypt certificate for the domain, so there is no need to issue additional certificates.