GitLab Pages custom domains

You can use custom domains:

• With GitLab Pages.
• To bypass user email confirmation for SAML- or SCIM-provisioned users. When using custom domains this way, you use the GitLab Pages feature but can skip the prerequisites.

To use one or more custom domain names:

• Add a custom root domain or subdomain.
• Add SSL/TLS certification.

Set up a custom domain

To set up Pages with a custom domain, complete the following steps.

Prerequisites

• An administrator has configured the server for GitLab Pages custom domains.
• A GitLab Pages website up and running, served under the default Pages domain (*.gitlab.io, for GitLab.com).
• A custom domain name example.com or subdomain subdomain.example.com.
• Access to your domain’s server control panel to set up DNS records:
  • A DNS record (A, AAAA, ALIAS, or CNAME) pointing your domain to the GitLab Pages server. If there are multiple DNS records on that name, you must use an ALIAS record.
  • A DNS TXT record to verify your domain’s ownership.

For an overview on DNS records, see GitLab Pages DNS records.

Step 1: Add a custom domain

To add your custom domain to GitLab Pages:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. In the upper-right corner, select New Domain.
4. In Domain, enter the domain name.
5. Optional. In Certificate, turn off the Automatic certificate management using Let’s Encrypt toggle to add an SSL/TLS certificate. You can also add the certificate and key later.
6. Select Create New Domain.

Step 2: Get the verification code

After you add a new domain to Pages, GitLab displays a verification code. Copy the values and paste them in your domain’s control panel as a TXT record in the next step.

The structure of the Verification status field is:

• Name/Host:
  • For root domains: _gitlab-pages-verification-code.example.com
  • For subdomains: _gitlab-pages-verification-code.subdomain.example.com
• DNS record type: TXT
• Value: gitlab-pages-verification-code=00112233445566778899aabbccddeeff (use your actual code from GitLab)

Step 3: Set up DNS records

To set up DNS records according to the type of domain you want to use with your Pages site, choose one of the following:

• For root domains
• For subdomains
• For both root and subdomains

For root domains

Root domains (example.com) require:

• At least one of:
  • A DNS A record pointing your domain to the Pages server.
  • A DNS AAAA record pointing your domain to the Pages server.
• A TXT record to verify your domain’s ownership.

For projects on GitLab.com, the IPv4 address is 35.185.44.232 and the IPv6 address is 2600:1901:0:7b8a::.

For projects in other GitLab instances (CE or EE), contact your system administrator and request the Pages server IP address for your instance.

For subdomains

Subdomains (subdomain.example.com) require:

• A DNS ALIAS or CNAME record pointing your subdomain to the Pages server.
• A DNS TXT record to verify your domain’s ownership.

Whether it’s a user or a project website, the DNS record should point to your Pages domain (namespace.gitlab.io), without any path.

For both root and subdomains

To point both the root domain and subdomain to the same website, for example, example.com and www.example.com, you need the following:

• A DNS A record for the domain.
• A DNS AAAA record for the domain.
• A DNS ALIAS/CNAME record for the subdomain.
• A DNS TXT record for each.

If you’re using Cloudflare, see redirecting www.domain.com to domain.com with Cloudflare.

Additionally:

• Do not use a CNAME record if you want to point your domain.com to your GitLab Pages site. Use an A record instead.
• Do not add any special chars after the default Pages domain. For example, do not point subdomain.domain.com to or namespace.gitlab.io/. Some domain hosting providers may request a trailing dot (namespace.gitlab.io.).
• GitLab Pages IP on GitLab.com was changed in 2017.
• GitLab Pages IP on GitLab.com has changed from 52.167.214.135 to 35.185.44.232 in 2018.
• IPv6 support was added to GitLab.com in 2023.

Step 4: Verify the domain’s ownership

After you have added all the DNS records:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Next to the domain name, select Edit ( ).
4. In Verification status, select Retry verification ( ).

When your domain becomes active, your website is available through your domain name.

Additionally:

• Domain verification is required for GitLab.com users. For GitLab Self-Managed, your GitLab administrator has the option to disabled custom domain verification.
• DNS propagation may take some time (up to 24 hours), although it’s usually a matter of minutes to complete. Until it does, verification fails, and attempts to visit your domain result in a 404.
• After your domain is verified, leave the verification record in place. Your domain is periodically reverified, and may be disabled if the record is removed.

Add more domain aliases

You can add more than one alias (custom domains and subdomains) to the same project. An alias can be understood as having many doors leading to the same room.

All the aliases you’ve set to your site are listed on Setting > Pages. From that page, you can view, add, and remove them.

Redirect www.domain.com to domain.com with Cloudflare

If you use Cloudflare, you can use page rules to redirect www.domain.com to domain.com without adding both domains to GitLab:

1. In Cloudflare, create at least one of:
   • A DNS A record pointing domain.com to 35.185.44.232.
   • A DNS AAAA record pointing domain.com to 2600:1901:0:7b8a::.
2. In GitLab, add the domain to GitLab Pages and get the verification code.
3. In Cloudflare, create a DNS TXT record to verify your domain.
4. In GitLab, verify your domain.
5. In Cloudflare, create a DNS CNAME record pointing www to domain.com.
6. In Cloudflare, add a Page Rule pointing www.domain.com to domain.com:
   1. Go to your domain’s dashboard. On the top navigation, select Page Rules.
   2. Select Create Page Rule.
   3. Enter the domain www.domain.com and select + Add a Setting.
   4. From the dropdown list, choose Forwarding URL, then select the status code 301 - Permanent Redirect.
   5. Enter the destination URL https://domain.com.

Add an SSL/TLS certificate to Pages

To secure your custom domain with GitLab Pages, you can:

• Use the Let’s Encrypt integration to automatically obtain and renew SSL certificates.
• Manually add SSL/TLS certificates.

For an overview of SSL/TLS certification, see GitLab Pages SSL/TLS certificates.

Manually add SSL/TLS certificates

Prerequisites:

• A GitLab Pages website up and running, accessible on a custom domain.

• The following certificate components:

  • PEM certificate: The certificate generated by the CA.
  • Intermediate certificate: Also called a root certificate, this identifies the CA. Usually combined with the PEM certificate, but some certificates like Cloudflare certificates require you to add them separately.
  • Private key: An encrypted key that validates your PEM against your domain.

To add a certificate when you create a new domain:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. In the upper-right corner, select New Domain.
4. In Domain, enter the domain name.
5. In Certificate, turn off the Automatic certificate management using Let’s Encrypt toggle.
6. Complete the certificate fields.
7. Select Create New Domain.

To add a certificate to an existing domain:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Next to the domain name, select Edit ( ).
4. In Certificate, turn off the Automatic certificate management using Let’s Encrypt toggle.
5. Complete the certificate fields.
6. Select Save changes.

When you complete the certificate fields:

• In Certificate (PEM), paste the PEM certificate. If your certificate requires a separate intermediate certificate, paste it in the same field, separated by a blank line. For more information, see Setting up GitLab Pages with Cloudflare certificates.
• In the private key field, paste your private key.

Force HTTPS for GitLab Pages websites

You can force HTTPS for GitLab Pages to automatically redirect HTTP requests to HTTPS with a 301 redirect. This works with the default GitLab Pages domain and custom domains with a valid certificate.

To force HTTPS:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Select the Force HTTPS (requires valid certificates) checkbox.
4. Select Save changes.

If you use Cloudflare CDN in front of GitLab Pages, set the SSL connection setting to full instead of flexible. For more information, see the Cloudflare CDN directions.

Edit a custom domain

You can edit a custom domain to:

• View the custom domain.
• View the DNS record to add.
• View the TXT verification entry.
• Retry verification.
• Edit the certificate settings.

To edit a custom domain:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Next to the domain name, select Edit ( ).

Delete a custom domain

After a custom domain is deleted, the domain is no longer verified in GitLab and cannot be used with GitLab Pages.

To delete and remove a custom domain:

1. On the top bar, select Search or go to and find your project.
2. Select Deploy > Pages.
3. Next to the domain name, select Remove domain ( ).
4. When prompted, select Remove domain.

Troubleshooting

Domain verification

To manually verify that you have properly configured the domain verification TXT DNS entry, you can run the following command in your terminal:

dig _gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN> TXT

Expect the output:

;; ANSWER SECTION:
_gitlab-pages-verification-code.<YOUR-PAGES-DOMAIN>. 300 IN TXT "gitlab-pages-verification-code=<YOUR-VERIFICATION-CODE>"

In some cases it can help to add the verification code with the same domain name as you are trying to register.

For a root domain:

For a subdomain: