GitLab Runner "x509: certificate signed by unknown authority": custom CA fixes

By Melih Toksari, developer of MergeBell · Updated · 4 min read

Short answer

GitLab Runner says "x509: certificate signed by unknown authority" when it doesn't trust the certificate of your GitLab server or a registry, usually because it's self-signed or comes from a private CA. For the runner itself, when you register it or in its log, save the CA certificate, in PEM format, as /etc/gitlab-runner/certs/gitlab.example.com.crt, named after the host, or point tls-ca-file in config.toml at it, then restart the runner. The runner passes that chain on to jobs, in the CI_SERVER_TLS_CA_FILE variable, for Git clones and artifacts. Image pulls need the CA on the Docker host, and commands in your script need it in the job image. GIT_SSL_NO_VERIFY only switches Git's check off, and it's insecure.

Registering a runner fails, or an existing runner stops picking up jobs, and its log says:

couldn't execute POST against https://gitlab.example.com/api/v4/jobs/request: Post "https://gitlab.example.com/api/v4/jobs/request": tls: failed to verify certificate: x509: certificate signed by unknown authority

Older runners leave out tls: failed to verify certificate:. Either way, the runner doesn’t trust the certificate your GitLab server presents, usually because it’s self-signed or comes from your company’s own certificate authority (CA). Here’s where to put that CA for each part of the job, with GitLab Runner 19.5.

Which part doesn’t trust it

Where it fails What needs the CA
gitlab-runner register, or the runner’s log The runner
The job’s Git clone: SSL certificate problem Usually a proxy, or a clone URL on another host
Pulling the job’s image from a private registry The Docker host
curl, npm or pip in your script The job’s image
docker push in Docker-in-Docker The docker:dind service

Trust the CA in the runner

  1. Get the certificate in PEM format. If GitLab’s certificate comes from your company’s CA, use the CA’s certificate, plus any intermediates, in one file. If the server’s certificate is self-signed, download it:

    openssl s_client -showcerts -connect gitlab.example.com:443 -servername gitlab.example.com < /dev/null 2>/dev/null | openssl x509 -outform PEM > /etc/gitlab-runner/certs/gitlab.example.com.crt
  2. Put it where the runner looks. As root, that’s /etc/gitlab-runner/certs/gitlab.example.com.crt, named after your GitLab host, without a port. Running as another user, it’s ~/.gitlab-runner/certs/. Or name the file yourself in config.toml:

    [[runners]]
      url = "https://gitlab.example.com/"
      tls-ca-file = "/etc/gitlab-runner/certs/ca.crt"

    When you register, gitlab-runner register --tls-ca-file=/etc/gitlab-runner/certs/ca.crt does the same. A runner running as a Windows service needs tls-ca-file.

  3. Check it with the same file. The output should end with Verify return code: 0 (ok):

    echo | openssl s_client -CAfile /etc/gitlab-runner/certs/gitlab.example.com.crt -connect gitlab.example.com:443 -servername gitlab.example.com
  4. Restart the runner with gitlab-runner restart, so it reads the new file.

The file must be PEM; DER isn’t supported. With the GitLab Runner Helm chart, store the certificate in a Kubernetes secret, under a key named after the host, such as gitlab.example.com.crt, and set certsSecretName to the secret’s name in values.yaml.

Git clones in the job

The runner passes the chain it trusts for GitLab on to jobs, in the file named by CI_SERVER_TLS_CA_FILE, and Git uses it for the GitLab host the runner connects to. So a clone that fails with one of these:

fatal: unable to access 'https://gitlab.example.com/group/project.git/': SSL certificate problem: unable to get local issuer certificate
fatal: unable to access 'https://gitlab.example.com/group/project.git/': SSL certificate problem: self-signed certificate in certificate chain

usually goes somewhere else:

  • Another host name, such as one set with clone_url in the runner’s config.toml. Give the runner a chain for that host too, or clone from the host the runner uses.
  • A proxy that presents its own certificate, while the openssl check above passes. GIT_CURL_VERBOSE: 1 in the job’s variables shows the connection; NO_PROXY: gitlab.example.com sends Git straight to GitLab.

GIT_SSL_NO_VERIFY: "true" makes Git skip the check altogether. GitLab’s docs call it a temporary and insecure workaround: anyone in between could serve a fake repository.

Image pulls

The runner doesn’t pull images itself: the Docker daemon on the runner’s host does, so the host needs the CA. Docker reads a CA for one registry from its own directory:

/etc/docker/certs.d/registry.example.com/ca.crt

Add the registry’s port to the directory name if it uses one, such as registry.example.com:5050. Or add the CA to the host’s system store, then restart Docker. On Kubernetes, each node’s container runtime needs it.

Your script’s own tools

The job’s image has its own certificate store, so curl, npm, pip and other tools don’t trust your CA by default.

  • For GitLab itself, use the chain the runner passes on: curl --cacert "$CI_SERVER_TLS_CA_FILE" ..., or export NODE_EXTRA_CA_CERTS="$CI_SERVER_TLS_CA_FILE" for Node.js.

  • For other hosts, or every tool, install the CA in each job container. In the runner’s config.toml, mount it and install it before every job:

    [[runners]]
      pre_build_script = """
      cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt
      update-ca-certificates --fresh > /dev/null
      """
      [runners.docker]
        volumes = ["/cache", "/etc/gitlab-runner/certs/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]

    The image needs the ca-certificates package, and the commands differ between distributions, so a runner that takes Alpine and Debian jobs needs a script that works on both. With the CA mounted at /etc/gitlab-runner/certs/ca.crt, the runner’s helper image also installs it for clones and artifacts.

In Docker-in-Docker, the docker:dind service runs its own daemon, which needs the CA before it starts: see Cannot connect to the Docker daemon.

Other x509 errors

  • x509: certificate has expired or is not yet valid: renew the server’s certificate, or fix the clock on the runner’s host.
  • x509: certificate is valid for a.example.com, not b.example.com: the url in config.toml must use a name the certificate lists.
  • x509: certificate relies on legacy Common Name field: the certificate has no subject alternative names, which current runners require. Reissue it with the host name as a SAN.

On your phone

MergeBell shows a job’s log live, so a certificate error in the clone step is there as soon as the runner writes it. The fix lives in the runner’s configuration, not your repository, so once it’s in place, Retry reruns the failed job on the free tier, with no new commit. More in how to retry a failed GitLab pipeline.

Frequently asked questions

How do I fix "x509: certificate signed by unknown authority" when registering a GitLab runner?

Give the runner your GitLab server's CA certificate in PEM format. Save it as /etc/gitlab-runner/certs/gitlab.example.com.crt, named after your GitLab host, or pass it with gitlab-runner register --tls-ca-file=/path/ca.crt, which saves tls-ca-file in config.toml. Use the CA's certificate, with any intermediates, not just the server's own certificate, unless that's self-signed. Restart an existing runner after you change it.

Where does GitLab Runner look for custom CA certificates?

In the file set by tls-ca-file in the runner's [[runners]] section. Without it, in /etc/gitlab-runner/certs/<host>.crt when the runner runs as root, ~/.gitlab-runner/certs/<host>.crt as another user, or ./certs/<host>.crt on other systems. The name is the GitLab host without a port, and the file must be PEM; DER isn't supported. On top of that, the runner trusts the system's certificate store.

Why does git clone fail in a GitLab CI job with "SSL certificate problem"?

The runner passes the CA chain it trusts for GitLab to the job in CI_SERVER_TLS_CA_FILE, and Git uses it for the GitLab host the runner connects to. A clone still fails when it goes to another host name, such as one set with clone_url in the runner's config.toml, or through a proxy that presents its own certificate. Set GIT_CURL_VERBOSE: 1 to see the connection, and NO_PROXY to your GitLab host to bypass the proxy.

How do I use a custom CA certificate in a GitLab CI job's script?

For your GitLab server, use the file in CI_SERVER_TLS_CA_FILE, such as curl --cacert "$CI_SERVER_TLS_CA_FILE", or NODE_EXTRA_CA_CERTS for Node.js. For other hosts, mount the CA into job containers with volumes in the runner's config.toml, and install it before each job with a pre_build_script that runs update-ca-certificates.

Is GIT_SSL_NO_VERIFY a safe fix for GitLab Runner certificate errors?

No. Setting GIT_SSL_NO_VERIFY: "true" makes Git in the job skip certificate checks, so anyone in the middle could serve a fake repository. GitLab's docs call it a temporary and insecure workaround. It also doesn't fix runner registration or image pulls, which don't use Git.

Sources

Checked against these pages on 11 November 2026. GitLab changes quickly — if something here no longer matches, tell us and we will fix it.

Do this from your phone with MergeBell

Free for the whole review loop: the To-Do inbox, diffs and line comments, approve and merge, pipelines with retry, and push alerts for your To-Dos. Works with gitlab.com and self-managed GitLab 16.0+.

Get MergeBell for iPhoneGet MergeBell for Android

On the App Store for iOS 26 or later and on Google Play for Android 12 or later. An independent app, not affiliated with GitLab Inc.