GitLab Pages
With GitLab Pages, you can host static websites for your existing Git repositories. A complete list of all features can also be found in the official GitLab documentation at: https://docs.gitlab.com/ee/administration/pages/
Prerequisites
- GitLab 18 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)
Enabling GitLab Pages
The following steps are required for the configuration and initial setup of GitLab Pages:
Wildcard DNS Record
To use the GitLab Pages integration, you must create a wildcard DNS record for the GitLab Pages module. The DNS record must not be a subdomain of the existing instance.
| RR Type | Host | Value |
|---|---|---|
| A | pages | GitLab server IPv4 address |
| AAAA | pages | GitLab server IPv6 address |
| A | *.pages | GitLab server IPv4 address |
| AAAA | *.pages | GitLab server IPv6 address |
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 acceptable. Using the subdomain pages.git.company.com is not permitted.
Deploy a Wildcard SSL Certificate on the GitLab Server Instance
We recommend using a paid wildcard SSL certificate, such as our Sectigo Essential SSL certificate.
See also: https://www.creoline.com/de/certificates
Customizing the GitLab Configuration
Once the necessary DNS records have been set up and the required SSL certificate has been issued, you can begin configuring 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.
Adjust the configuration as follows; you can also find the corresponding line number in the configuration file in the image below:
To navigate more quickly when editing large configuration files, you can also use Ctrl + F (Windows) or Command + F (macOS) to search within the configuration file for a specific term or similar.
Enter the desired new GitLab URL in the pages_external_url section.
Example:
pages_external_url "https://pages.company.com"To ensure that the feature is enabled and works properly with your web server, you must also add or enable the following settings in the configuration file:
# Enable the GitLab Pages module
gitlab_pages['enable'] = true
# Serve the GitLab Pages module via nginx
pages_nginx['enable'] = true
# Automatically redirect the GitLab Pages module to https://
pages_nginx['redirect_http_to_https'] = true Configuring pages_nginx['ssl_certificate'] and pages_nginx['ssl_certificate'] is only necessary 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 (including 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 |
Next, place both certificate components in the /etc/gitlab/ssl directory via SSH or FTP/SFTP as described earlier.
Next, enter a brief message in the "Change Message" field explaining why the GitLab URL was changed, and save the changes by clicking the Save Changes button.
Saving the configuration automatically triggers the deployment of the configuration and the subsequent restart of GitLab. Notify active users in advance about the planned change.
You can view the deployment status on the Deployments tab.
Once the deployment has completed successfully, you can access the general settings for the GitLab Pages integration via the GitLab web interface.
To do this, navigate to the following menu item: Admin → Settings → Preferences → Pages
Enable GitLab Pages integration for an existing repository
Navigate to the desired repository and select the Settings → Pages menu item. From here, you can customize the pipeline configuration via the gitlab-ci.yml file to enable GitLab Pages.
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. To integrate custom domains, an additional IPv4 and IPv6 address is required.
Additional IPv4 addresses can be ordered directly via our live chat or through our ticket system. Current prices for additional IP addresses can be found in the article Pricing for Additional and Special Services.
Once the additional IP addresses have been configured 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 portion of custom domains. You can use the primary domain as well as any subdomain. After you have created the required DNS records, you can set up the custom domain in the repository settings. GitLab automatically attempts to obtain a Let’s Encrypt certificate for the domain, eliminating the need to issue additional certificates.
