SimpleACME
Sign inCreate account →
Software guides

GitLab HTTPS with externally renewed certificates and delegated DNS validation

Configure GitLab Linux package HTTPS with external certificates, delegated DNS validation, runner checks and a safe NGINX renewal deployment.

GitLab is more than a login page. Its public address appears in clone commands, webhook payloads, runner configuration, OAuth callbacks and emails. Changing HTTPS carelessly can leave the browser working while automation fails. This guide treats certificate deployment as a GitLab configuration change with a measurable result: the Linux package presents the expected certificate, existing Git operations still work, and the next renewal follows the same controlled path.

Release assumption: an existing supported GitLab Linux package installation using its bundled NGINX, with the configuration interface described in the current Linux package documentation checked in November 2026. This is not a Helm, Operator or source-installation recipe. Inspect your installed version and its matching documentation before applying it. Commands below are examples for an administrator with root access; they have not been executed against your GitLab server.

The example name is gitlab.example.com. Replace it everywhere and retain the real database, repository and backup settings already present in your configuration. An HTTPS change does not require rebuilding GitLab or moving its repositories.

Step 1: Record the working GitLab configuration

Start with the application URL and the current certificate owner. Determine whether the package obtains certificates itself, a reverse proxy terminates HTTPS, or an external process already installs files. There should be one renewal owner for each listening endpoint. Two tools replacing the same files can produce confusing apparent rollbacks after an otherwise successful renewal.

Keep a protected copy of /etc/gitlab/gitlab.rb and the current certificate directory. GitLab configuration can contain credentials, so a backup belongs in administrator-only storage rather than a repository. Record the current certificate fingerprint and expiry from a client that uses the actual hostname. Also note any separate registry or Pages addresses: a certificate for the main site does not automatically cover those names.

sudo gitlab-rake gitlab:env:info
sudo gitlab-ctl status
sudo install -d -m 0700 /root/gitlab-tls-before
sudo cp -a /etc/gitlab/gitlab.rb /root/gitlab-tls-before/
sudo cp -a /etc/gitlab/ssl /root/gitlab-tls-before/ssl
openssl s_client -connect gitlab.example.com:443 \
  -servername gitlab.example.com </dev/null 2>/dev/null \
  | openssl x509 -noout -dates -fingerprint -sha256

If /etc/gitlab/ssl does not exist yet, omit that copy and document that this is the first external certificate installation. Do not interpret a missing directory as permission to remove unrelated package files. Confirm SSH access before starting, because it remains your recovery route if the web listener cannot start.

Write a short acceptance checklist before making changes: a browser login, an HTTPS clone or fetch, a runner contacting GitLab, and one representative webhook. This makes success specific to the way your organization uses GitLab instead of relying on a single green status page.

Step 2: Delegate only the certificate challenge

With SimpleACME, create the registration for the certificate name in your account, activate paid update access, and add the exact challenge CNAME supplied by the portal. For this example the owner is _acme-challenge.gitlab.example.com. Its target must be the generated registration target, not an address copied from somebody else's walkthrough. Keep the normal website A or AAAA record pointing at GitLab.

The CNAME delegates ACME challenge answers; it does not move your zone or route web traffic. An ACME client such as Certbot still requests the certificate from the certificate authority and keeps its private key. SimpleACME accepts authenticated delegated TXT updates for an existing registration. It neither issues GitLab certificates nor needs a general API credential for your normal DNS provider.

Use the maintained Certbot integration instructions and API documentation to configure that client. Store its registration credentials in a root-readable file, not inside a GitLab project or runner job log. A free demo registration can prepare DNS, but does not grant update access for issuance or renewal.

Check the CNAME using an external resolver, and allow old negative answers to expire if you have just created it. A successful SimpleACME TXT update is evidence of challenge activity, not proof that the certificate authority completed issuance. Your renewal system must inspect the client result and the resulting certificate separately.

Step 3: Install the certificate and disable package issuance

After the ACME client has produced a real certificate, inspect its subject alternative names, validity and matching private key. Use the full chain, with the leaf first and required intermediates following. Do not substitute an unrelated root certificate for the issued chain. Install a private deployment copy in the package certificate directory so GitLab does not depend on the permissions and symlink layout of the client's archive.

sudo install -d -m 0755 /etc/gitlab/ssl
sudo install -m 0644 /etc/letsencrypt/live/gitlab.example.com/fullchain.pem \
  /etc/gitlab/ssl/gitlab.example.com.crt
sudo install -m 0600 /etc/letsencrypt/live/gitlab.example.com/privkey.pem \
  /etc/gitlab/ssl/gitlab.example.com.key

Merge the following settings into /etc/gitlab/gitlab.rb; do not replace the entire file. GitLab documents manual HTTPS and explicitly disabling its Let's Encrypt integration when another certificate owner is used. GitLab Linux package SSL documentation.

external_url 'https://gitlab.example.com'
letsencrypt['enable'] = false
nginx['ssl_certificate'] = '/etc/gitlab/ssl/gitlab.example.com.crt'
nginx['ssl_certificate_key'] = '/etc/gitlab/ssl/gitlab.example.com.key'

Choose whether port 80 should redirect to HTTPS according to your access policy. DNS-01 does not require opening it for certificate validation. Conversely, closing port 80 is not a requirement of SimpleACME; existing redirects may be useful to people following old links. Keep this transport choice separate from the ACME challenge configuration.

If a separate registry hostname is enabled, review its own certificate settings rather than assuming the main NGINX certificate covers everything. An exact-name certificate is often easier to inventory than sharing a wildcard private key across the GitLab site, registry and unrelated services.

Step 4: Reconfigure once and verify real GitLab traffic

Apply the initial configuration during a maintenance window. Reconfigure generates package-managed configuration from gitlab.rb; editing the generated NGINX file directly would be temporary and makes later operations unpredictable. Package maintenance commands and service control are documented separately by GitLab. GitLab maintenance commands.

sudo gitlab-ctl reconfigure
sudo gitlab-ctl status nginx
sudo gitlab-ctl tail nginx

Watch the command result and logs rather than assuming a returned shell prompt means success. Check the public listener from another host with SNI and normal trust validation. Confirm the new certificate fingerprint, then perform the application checks you recorded earlier. A runner that still references the old HTTP URL is an application configuration issue, not necessarily a certificate failure.

curl --fail --show-error --head https://gitlab.example.com/users/sign_in
git ls-remote https://gitlab.example.com/your-group/your-test-project.git

Use a repository you are allowed to read and your organization's normal credential mechanism. Do not place a personal access token in the command line simply to make this example work. An authentication prompt or an authorization denial can still prove TLS succeeded, but it does not replace a proper functional check.

If validation fails, keep the failure layer clear. A connection refusal points toward listeners or firewall rules. A name mismatch points toward certificate coverage or SNI. A missing intermediate commonly affects command-line clients before browsers with cached intermediates. A GitLab error page after successful TLS belongs to the application layer.

Step 5: Renew with an application-aware deployment boundary

Configure the ACME client's successful-renewal deployment stage to validate the candidate files before replacing the installed pair. It should reject an expired certificate, a certificate without gitlab.example.com, an unreadable key, or a mismatched public key. Stage both files in a protected directory and preserve the last installed pair before promotion. Serialize deployments so two renewal processes cannot interleave their copies.

For an unchanged GitLab configuration, a certificate deployment should normally finish by reloading the bundled NGINX rather than running every GitLab service through a restart. The package exposes the NGINX signal command below. Check the command's exit status and then verify the certificate actually served on port 443; a reload can leave an old worker serving existing connections while new connections use the new certificate.

sudo gitlab-ctl hup nginx
openssl s_client -connect gitlab.example.com:443 \
  -servername gitlab.example.com -verify_return_error </dev/null

Keep issuer renewal scheduling separate from deployment monitoring. An ACME job can succeed while a subsequent copy or reload fails. Alert on the certificate presented by GitLab as well as on client job failures. Record its serial number, expiry and successful deployment time, and retain enough history to explain which operation changed it.

Rollback means reinstalling the previous unexpired certificate and matching key, restoring gitlab.rb if it changed, and reloading or reconfiguring as appropriate. Do not re-enable package issuance merely as a panic reaction: that introduces another issuer path and may fail for exactly the network restrictions that motivated delegated DNS validation. If the previous certificate is expired, restoring it is not a successful recovery; repair deployment or issue a replacement through the established client.

A separate acceptance check for runners and registry clients

For a runner fleet, choose a runner that represents the actual executor and network segment used in production. Have it fetch a small existing repository and report its normal job result. An administrator's workstation may use a different CA bundle and resolver from a container executor. If only one runner fails, compare that runner's trust environment before changing the working GitLab listener for everyone.

Registry clients deserve an independent check when GitLab's container registry uses another hostname. Record that endpoint's own certificate and perform an authorized pull of a harmless existing image. A successful Git clone over HTTPS does not exercise the registry listener, its authentication redirect or its certificate chain. Keep those results next to the main-site check so a partial rollout is not recorded as complete.

During later package upgrades, review the external certificate settings as part of the change checklist. Reconfiguration should continue to use the declared external files and disabled built-in issuer. Avoid manually patching generated NGINX configuration to preserve a one-off workaround; the next reconfigure can overwrite it. Instead, correct the supported gitlab.rb settings and verify the resulting listener again.

When collecting incident evidence, include timestamps, certificate fingerprints, command exit status and the failing client category. Exclude the private key, registration password and access tokens. That limited record is usually enough to distinguish stale deployment from a client trust problem without creating a new secret exposure.

Frequently asked questions

Does SimpleACME replace GitLab's certificate authority?

No. Your ACME client communicates with the authority, creates or retains the private key, and obtains the certificate. SimpleACME supplies the delegated DNS challenge updates. GitLab consumes the issued files after your deployment procedure validates them.

Must I expose GitLab over HTTP for renewals?

DNS-01 validation does not require an inbound HTTP challenge listener. GitLab can remain available only through your intended HTTPS or private network path. Public DNS still needs to answer the delegated challenge correctly, and the ACME client needs outbound access to the authority and update API.

Can one wildcard certificate cover the registry too?

A wildcard covers one label beneath its base name and does not cover the base name itself. Include every required identifier deliberately, check the certificate's actual SAN list, and consider the risk of distributing one wildcard private key to several components. Separate certificates can make ownership and recovery clearer.

Why did a renewal succeed while GitLab still shows the old expiry?

Issuance, installation and listener reload are different stages. Inspect the ACME output path, the deployment copy, the reload result and the certificate served on a new connection. The SimpleACME DNS activity timeline cannot prove that GitLab loaded a particular certificate.

KEEP EXPLORING

A little more clarity.

ONE CNAME. A REPEATABLE WORKFLOW.

Your next certificate. A little less complicated.

Keep your DNS provider and your ACME client.
Prepare your domain before activating paid updates.

Create your account →Explore the integrations