GitLab + GitLab Runner (Pitfalls and Good Practices)

Recently we started using GitLab including the CI/CD features here at KeyIdentity. During the first weeks we stumbled upon some issues, which can make it a bit hard to get it up and running. Our Setup includes a GitLab Server installed via Omnibus ( and some GitLab-runners within docker. In addition, we are using a docker registry which requires authentication for pull and push. In this article we wanted to share how, we solved problems, when setting up the CI/CD system of GitLab.

1) Using own CA or a self-signed certificate on GitLab and trying to connect a GitLab-runner to it

You may see an error like this, when trying to register the runner:
x509: certificate signed by unknown authority
Fix it by adding the “–tls-ca-file” parameter to the gitlab-runner register command.

gitlab-runner register -n \
--tls-ca-file=/path/to/my/ca.pem \
--url= \
--registration-token= \


2) “Cannot connect to the Docker daemon…”

Your runner ist not able to connect to the docker-deamon to spawn additional docker container for your tests or builds. The error you may run into looks like this:
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? 
Fix it by adding the privileged flag to the configuration or add to corresponding parameter to the register command:

Register command:

gitlab-runner register -n \

Config file at /etc/gitlab-runner/config.toml

 name = "my-runner-1"
 url = ""
 token = "yourToken"
 privileged = true

Explanations and Manual:

3) Using an internal docker registry with SSL and own CA

It is very likely that the error looks quite similar to the one mentioned at 1).
ERROR: Preparation failed: Error response from daemon: Get x509: certificate signed by unknown authority

This error can have two different causes:

1) Your docker host is missing your CA file.
If so, include it by using “update-ca-certificates” on Debian / Ubuntu -based Linux systems (
In short:
Place your ca file with .crt extension (important!) into “/usr/local/share/ca-certificate”

 run "sudo update-ca-certificates"

2) When using docker-in-docker (dind), you have probably a part like this in your gitlab-ci.yml

 image: docker:latest
 - docker:dind

More details on this can be found here:

In this case the error is arised from the “docker:dind” container.
The only resolution i found for this, was adding the CA-file into the “docker:dind” container, resulting in a new, self-build image:
Your own dind-Dockerfile may look like this:

FROM docker:dind

COPY /root-ca/ca.crt /usr/local/share/ca-certificates/ca.crt

RUN update-ca-certificates

After building and pushing to your internal docker registry, you can use your own “docker:dind” in your .gitlab-ci.yml

image: docker:latest

This problem is known and discussed at GitLab.

4) Using an internal docker registry with Basic-Auth

Trying to pull from the internal docker-registry will fail, if it is read-protected and the gitlab-runner has no credentials.
This can be resolved by adding credentials to your gitlab-runner config.toml.
Create a TOKEN, based in username and password.

echo -n 'user:password' | base64

Add your docker-registry URL and the TOKEN this code snippet and add it to your config. Restart the service after adding the line 😉

 environment = ["DOCKER_AUTH_CONFIG={ \"auths\": { \"\": { \"auth\": \"TOKEN\" } } }"]


Further Reading:

There are two very helpful websites, which help a lot, when getting started:
1) The manual for the .gitlab-ci.yml, which can be found here

2) The list of available environment variables during a job run

Happy CI/CD!

Feel free to share the newsShare on Facebook
Share on Google+
Tweet about this on Twitter
Share on LinkedIn

Published by

Andreas Bauer

DevOps Engineer