Self-signed certificates or custom Certification Authorities

`Supported options for self-signed certificates targeting the GitLab server`

This section refers to the situation where only the GitLab server requires a custom certificate. If other hosts (e.g. object storage service without proxy download enabled ) also require a custom certificate authority (CA), please see the next section .

GitLab Runner supports the following options:


       
        
         Default - Read the system certificate
        
        : GitLab Runner reads the system certificate store and verifies the
GitLab server against the certificate authorities (CA) stored in the system. Note that reading from
the system certificate store is
        
         not supported in Windows
        
        .
       
       
        
         
          Specify a custom certificate file
         
         : GitLab Runner exposes the
         
          tls-ca-file
         
         option during
         
          registration
         
         (
         
          gitlab-runner register --tls-ca-file=/path
         
         ), and in
         
          
           config.toml
          
         
         under the
         
          [[runners]]
         
         section. This allows you to specify a custom certificate file.
This file will be read every time the Runner tries to access the GitLab server.
If you are using GitLab Runner Helm chart, you will need to configure certificates as described in
         
          Providing a custom certificate for accessing GitLab
         
         .
        
       
       
        
         
          Read a PEM certificate
         
         : GitLab Runner reads the PEM certificate (
         
          DER format is not supported
         
         ) from a
predefined file:
        
        
         
          
           /etc/gitlab-runner/certs/gitlab.example.com.crt
          
          on *nix systems when GitLab Runner is executed as
          
           root
          
          .
         
         
          If your server address is
          
           https://gitlab.example.com:8443/
          
          , create the
certificate file at:
          
           /etc/gitlab-runner/certs/gitlab.example.com.crt
          
          .
         
         
          You can use the
          
           openssl
          
          client to download the GitLab instance’s certificate to
          
           /etc/gitlab-runner/certs
          
          :
         
         
          
           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

          
         
         
          To verify that the file is correctly installed, you can use a tool like
          
           openssl
          
          . For example:
         
         
          
           echo | openssl s_client -CAfile /etc/gitlab-runner/certs/gitlab.example.com.crt -connect gitlab.example.com:443 -servername gitlab.example.com
~/.gitlab-runner/certs/gitlab.example.com.crt on *nix systems when GitLab Runner is executed as non-root.
./certs/gitlab.example.com.crt on other systems. If running GitLab Runner as a Windows service,
this will not work. Specify a custom certificate file instead.

Notes:


       
        
         If your GitLab server certificate is signed by your CA, use your CA certificate
(not your GitLab server signed certificate). You might need to add the intermediates to the chain as well.
For example, if you have a primary, intermediate, and root certificate,
you can put all of them into one file:
        
        
         
            -----BEGIN CERTIFICATE-----
  (Your primary SSL certificate: your_domain_name.crt)
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  (Your intermediate certificate)
  -----END CERTIFICATE-----
  -----BEGIN CERTIFICATE-----
  (Your root certificate)
  -----END CERTIFICATE-----

         
        
        
         If you are updating the certificate for an existing Runner,
         
          restart it
         
         .
        
        
         If you already have a Runner configured through HTTP, update your instance path to the new HTTPS URL of your GitLab instance in your
         
          config.toml
         
         .
        
        
         As a temporary and insecure workaround, to skip the verification of certificates,
in the
         
          variables:
         
         section of your
         
          .gitlab-ci.yml
         
         file, set the CI variable
         
          GIT_SSL_NO_VERIFY
         
         to
         
          true
         
         .

`Git cloning`

The Runner injects missing certificates to build the CA chain by using CI_SERVER_TLS_CA_FILE . This allows git clone and artifacts to work with servers that do not use publicly trusted certificates.

This approach is secure, but makes the Runner a single point of trust.

`Trusting TLS certificates for Docker and Kubernetes executors`

There are two contexts that need to be taken into account when we consider registering a certificate on a container:


       
        
        
        
         
          The
         
         
          
           user image
          
         
         , which is used to run the user script.
For scenarios that involve trusting the certificate for user scripts, the user must take ownership regarding how to install a certificate, since this is
highly dependent on the image itself, and the Runner has no way of knowing how to install a certificate in each
possible scenario.
        
        
         The
         
          
           Runner helper image
          
         
         , which is used to handle Git, artifacts, and cache operations.
For scenarios that involve trusting the certificate for other CI/CD stages, the user only needs to make a certificate file
available at a specific location (for example,
         
          /etc/gitlab-runner/certs/ca.crt
         
         ), and the Docker container will
automatically install it for the user.

`Trusting the certificate for user scripts`

If your build script needs to communicate with peers through TLS and needs to rely on a self-signed certificate or custom Certificate Authority, you will need to perform the certificate installation in the build job, as the Docker container running the user scripts doesn’t have the certificate files installed by default. This might be required to use a custom cache host, perform a secondary git clone , or fetch a file through a tool like wget , for example.

To install the certificate:


       
        
         
          Map the necessary files as a Docker volume so that the Docker container that will run
the scripts can see them. Do this by adding a volume inside the respective key inside
the
          
           [runners.docker]
          
          in the
          
           config.toml
          
          file, for example:
         
        
        
         
          
           
            Linux
           
           :
          
         
         
          
          
          
           
           
             [[runners]]
   name = "docker"
   url = "https://example.com/"
   token = "TOKEN"
   executor = "docker"
   [runners.docker]
     image = "ubuntu:latest"
     # Add path to your ca.crt file in the volumes list
     volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
Linux-only: Use the mapped file (e.g ca.crt) in a pre_build_script that:

Copies it to /usr/local/share/ca-certificates/ca.crt inside the Docker container.

Installs it by running update-ca-certificates --fresh. For example (commands
vary based on the distribution you’re using):

On Ubuntu:

  [[runners]]
    name = "docker"
    url = "https://example.com/"
    token = "TOKEN"
    executor = "docker"
    # Copy and install CA certificate before each job
    pre_build_script = """
    apt-get update -y > /dev/null
    apt-get install -y ca-certificates > /dev/null
    cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt
    update-ca-certificates --fresh > /dev/null
On Alpine:

  [[runners]]
    name = "docker"
    url = "https://example.com/"
    token = "TOKEN"
    executor = "docker"
    # Copy and install CA certificate before each job
    pre_build_script = """
    apk update >/dev/null
    apk add ca-certificates > /dev/null
    rm -rf /var/cache/apk/*
    cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/ca.crt
    update-ca-certificates --fresh > /dev/null

If you just need the GitLab server CA cert that can be used, you can retrieve it from the file stored in the CI_SERVER_TLS_CA_FILE variable:

       curl --cacert "${CI_SERVER_TLS_CA_FILE}"  ${URL} -o ${FILE}

      


       
        
         
          Trusting the certificate for the other CI/CD stages
          
          
          
           
           
           
            Introduced
           
           in GitLab 13.3.
          
          
           You can map a certificate file to
           
            /etc/gitlab-runner/certs/ca.crt
           
           on Linux,
or
           
            C:\GitLab-Runner\certs\ca.crt
           
           on Windows.
The Runner helper image installs this user-defined
           
            ca.crt
           
           file at start-up, and uses it
when performing operations like cloning and uploading artifacts, for example.
          
          
           Docker
           
            
             
              Linux
             
             :
            
           
           
            
            
            
             
             
               [[runners]]
   name = "docker"
   url = "https://example.com/"
   token = "TOKEN"
   executor = "docker"
   [runners.docker]
     image = "ubuntu:latest"
     # Add path to your ca.crt file in the volumes list
     volumes = ["/cache", "/path/to-ca-cert-dir/ca.crt:/etc/gitlab-runner/certs/ca.crt:ro"]
Windows:

  [[runners]]
   name = "docker"
   url = "https://example.com/"
   token = "TOKEN"
   executor = "docker"
   [runners.docker]
     image = "mcr.microsoft.com/windows/servercore:21H2"
     # Add directory holding your ca.crt file in the volumes list
     volumes = ["c:\\cache", "c:\\path\\to-ca-cert-dir:C:\\GitLab-Runner\\certs:ro"]
Kubernetes
To provide a certificate file to jobs running in Kubernetes:

Store the certificate as a Kubernetes secret in your namespace:

kubectl create secret generic <SECRET_NAME> --namespace <NAMESPACE> --from-file=<CERT_FILE>
Mount the secret as a volume in your runner, replacing <SECRET_NAME>
and <LOCATION> with appropriate values:

gitlab-runner:
  runners:
   config: |
     [[runners]]
       [runners.kubernetes]
         namespace = "{{.Release.Namespace}}"
         image = "ubuntu:latest"
       [[runners.kubernetes.volumes.secret]]
           name = "<SECRET_NAME>"
           mount_path = "<LOCATION>"
The mount_path is the directory in the container where the certificate is stored.
If you used /etc/gitlab-runner/certs/ as the mount_path and ca.crt as your
certificate file, your certificate is available at /etc/gitlab-runner/certs/ca.crt
inside your container.

As part of the job, install the mapped certificate file to the system certificate store.
For example, in an Ubuntu container:

script:
  - cp /etc/gitlab-runner/certs/ca.crt /usr/local/share/ca-certificates/
  - update-ca-certificates
Due to a known issue in the Kubernetes executor’s
handling of the helper image’s ENTRYPOINT, the mapped certificate file isn’t automatically installed
to the system certificate store.
Troubleshooting
Refer to the general SSL troubleshooting
documentation.
In addition, you can use the tlsctl tool to debug GitLab certificates from the Runner’s end.

x509: certificate signed by unknown authority while trying to pull executor images from private registry
This error occurs when the Docker host or Kubernetes node where the runner schedules the
executors does not trust the certificate used by the private registry. To fix the error,
add the relevant root certificate authority certificate to the system’s trust store based
on your operating system.
            
           
           
            
             
              
               
                
                Help & feedback
                
               
               
                Docs
               
              
              
               Edit this page
              
              to fix an error or add an improvement in a merge request.
              

              
               Create an issue
              
              to suggest an improvement to this page.
              

              
               Product
              
              
               Create an issue
              
              if there's something you don't like about this feature.
              

              
               Propose functionality
              
              by submitting a feature request.
              

              
               Join First Look
              
              to help shape new features.
              
               Feature availability and product trials
              
              
               View pricing
              
              to see all GitLab tiers and features, or to upgrade.
              

              
               Try GitLab for free
              
              with access to all features for 30 days.
              

              
               Get Help
              
              
               If you didn't find what you were looking for,
               
                search the docs
               
               .
               

               If you want help with something specific and could use community support,
               
                post on the GitLab forum
               
               .
               

               For problems setting up or using this feature (depending on your GitLab
subscription).
               

              
              
               Request support

`Supported options for self-signed certificates targeting the GitLab server`

`Git cloning`

`Trusting TLS certificates for Docker and Kubernetes executors`

`Trusting the certificate for user scripts`

Kubernetes

`Troubleshooting`

`x509: certificate signed by unknown authority while trying to pull executor images from private registry`

Help & feedback

Docs

Product

Feature availability and product trials

Get Help