Troubleshooting TLS Certificate Verification Issues with GitLab Runner

When setting up GitLab Runners to connect to your GitLab instance, you may encounter TLS certificate verification errors, especially when using self-hosted GitLab servers or servers with certificates from certificate authorities (CAs) not included in your system’s default trust store. This article walks through diagnosing and resolving these issues to successfully register your GitLab Runner.

Understanding the Problem

Consider the following scenario: You’re trying to register a GitLab Runner with your company’s GitLab server hosted at example-gitlab.com using a command like:

gitlab-runner register --url https://example-gitlab.com --token glrt-abcDEF123456_example

But you encounter this error:

ERROR: Verifying runner... failed runner=abcDEF123 status=couldn't execute POST against https://example-gitlab.com/api/v4/runners/verify: Post "https://example-gitlab.com/api/v4/runners/verify": tls: failed to verify certificate: x509: certificate signed by unknown authority

This error indicates that while your GitLab server does have an SSL certificate, your system doesn’t recognize or trust the certificate authority that issued it. The specific error “certificate signed by unknown authority” means that your system’s certificate store lacks the necessary root or intermediate certificates to establish a chain of trust to the certificate authority.

Solution Options

There are four main approaches to resolving this issue:

Option 1: Install the missing CA certificates

Update your system’s certificate store to include the missing CA certificates.

Option 2: Provide the CA certificate explicitly

If you have access to the CA certificate file, you can provide it directly to the registration command.

Option 3: Skip TLS verification (for testing only)

This bypasses security checks and should only be used in controlled test environments.

Option 4: Download the certificate directly from the server

Extract the server’s certificate and use it for registration – this is often the most straightforward approach.

Step-by-Step Resolution Using Option 4

Let’s walk through the most practical solution – downloading the certificate directly from the server:

Extract the certificate from the server:
```
openssl s_client -showcerts -connect example-gitlab.com:443 </dev/null 2>/dev/null | openssl x509 -outform PEM > gitlab-cert.crt
```
This command connects to your GitLab server, retrieves the certificate, and saves it as gitlab-cert.crt.

Register the runner using the downloaded certificate:

gitlab-runner register --url https://example-gitlab.com \
  --token glrt-abcDEF123456_example \
  --tls-ca-file gitlab-cert.crt

Verify successful connection:

If the certificate is valid and correctly installed, the registration process will continue without the previous TLS verification error.

Completing the Runner Registration

After successfully resolving the TLS verification issue, you’ll need to complete the registration by answering a series of configuration questions:

Select an executor:
```
Enter an executor: docker+machine, kubernetes, docker-autoscaler, custom, parallels, docker, docker-windows, instance, shell, ssh, virtualbox:
```
The executor determines how your CI/CD jobs will run. For example, selecting shell will run jobs directly on the host machine, while docker runs each job in a fresh Docker container.
Provide a description for your runner (optional).
Add tags to control which jobs this runner can process.
Choose whether to run untagged jobs.
Decide whether to lock this runner to the current project.

Once you’ve answered these questions, the registration process will complete, and the runner configuration will be saved to /etc/gitlab-runner/config.toml.

Understanding Your Options in More Detail

About Executors

shell: Simplest option. Runs jobs directly on the host machine with no isolation.
docker: Good balance of isolation and simplicity. Runs each job in a fresh Docker container.
kubernetes: Ideal for cloud-native environments. Runs jobs as pods in a Kubernetes cluster.
ssh: Executes jobs on a remote machine via SSH connections.
docker+machine/docker-autoscaler: Advanced options for dynamic scaling of Docker hosts.
virtualbox/parallels: Run jobs in virtual machines for maximum isolation.

Conclusion

TLS certificate verification errors are common when setting up GitLab Runners, especially with self-hosted GitLab instances. By understanding the nature of the error and following the step-by-step process outlined in this article, you can successfully register your runner and begin automating your CI/CD pipelines.

Remember that while there are multiple approaches to solving this issue, extracting the certificate directly from the server (Option 4) is often the most straightforward and secure method, as it ensures you’re using the exact certificate presented by your GitLab server.