GitLab Pages Let's Encrypt certificates

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

Introduced in GitLab 12.1.

The GitLab Pages integration with Let's Encrypt (LE) allows you to use LE certificates for your Pages website with custom domains without the hassle of having to issue and update them yourself; GitLab does it for you, out-of-the-box.

Let's Encrypt is a free, automated, and open source Certificate Authority.

WARNING: This feature covers only certificates for custom domains, not the wildcard certificate required to run Pages daemon (Self-managed, Free, Premium, and Ultimate only). Wildcard certificate generation is tracked in this issue.

Prerequisites

Before you can enable automatic provisioning of an SSL certificate for your domain, make sure you have:

Created a project in GitLab containing your website's source code.
Acquired a domain (example.com) and added a DNS entry pointing it to your Pages website. The top-level domain (.com) must be a public suffix.
Added your domain to your Pages project and verified your ownership.
Verified your website is up and running, accessible through your custom domain.

The GitLab integration with Let's Encrypt is enabled and available on GitLab.com. For self-managed GitLab instances, make sure your administrator has enabled it.

Enabling Let's Encrypt integration for your custom domain

Once you've met the requirements, enable Let's Encrypt integration:

On the left sidebar, select Search or go to and find your project.
Select Deploy > Pages.
Next to the domain name, select Edit.
Turn on the Automatic certificate management using Let's Encrypt toggle.
Select Save changes.

Once enabled, GitLab obtains a LE certificate and add it to the associated Pages domain. GitLab also renews it automatically.

Notes:

Issuing the certificate and updating Pages configuration can take up to an hour.

If you already have an SSL certificate in domain settings it continues to work until replaced by the Let's Encrypt certificate.

Troubleshooting

Error "Something went wrong while obtaining the Let's Encrypt certificate"

Introduced in GitLab 13.0.

If you get an error Something went wrong while obtaining the Let's Encrypt certificate, first, make sure that your pages site is set to "Everyone" in your project's Settings > General > Visibility. This allows the Let's Encrypt Servers reach your pages site. Once this is confirmed, you can try obtaining the certificate again by following these steps:

On the left sidebar, select Search or go to and find your project.
Select Deploy > Pages.
Next to the domain name, select Edit.
In Verification status, select Retry verification ({retry}).
If you're still getting the same error:
1. Make sure you have properly set only one CNAME or A DNS record for your domain.
2. Make sure your domain doesn't have an AAAA DNS record.
3. If you have a CAA DNS record for your domain or any higher level domains, make sure it includes letsencrypt.org.
4. Make sure your domain is verified.
5. Go to step 1.

Message "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later." hangs for more than an hour

If you've enabled Let's Encrypt integration, but a certificate is absent after an hour and you see the message, "GitLab is obtaining a Let's Encrypt SSL certificate for this domain. This process can take some time. Please try again later.", try to remove and add the domain for GitLab Pages again by following these steps:

On the left sidebar, select Search or go to and find your project.
Select Deploy > Pages.
Next to the domain name, select Remove.
Add the domain again, and verify it.
Enable Let's Encrypt integration for your domain.
If you're still getting the same error:
1. Make sure you have properly set only one CNAME or A DNS record for your domain.
2. Make sure your domain doesn't have an AAAA DNS record.
3. If you have a CAA DNS record for your domain or any higher level domains, make sure it includes letsencrypt.org.
4. Go to step 1.