Common errors setting up Gitlab runner using the Docker executor

When you first register your Gitlab runner to use the Docker executor, you may run into the following issues:

• Problem1: You get a host unknown error when the runner attempts to checkout code: fatal: unable to access 'http://gitlab-ci-token:xxxxxxxxxxxxxxxxxxxx@my.server.com/my-projects/my-project.git/': Couldn't resolve host 'my.server.com'. Chances are you are not running a local DNS server that your Docker container can use to resolve my.server.com. 
• Problem 2: Everything is setup correctly but Gitlab runner always attempts to pull Docker images from Docker Hub.
• Problem 3: Gitlab runner may complain that you are checking out code in the root directory.

Below is a solution to each of the 3 stated problems above.

We will make the following assumptions for the purpose of this example:

•  Gitlab runner can access Gitlab server.

•  Local Docker image: my_runner_image

•  Hostname of machine hosting my Gitlab server: my.server.com

•  IP address of machine hosting my Gitlab server: 192.168.1.144

•  Default Gitlab runner configuration file: /etc/gitlab-runner/config.toml

•  If you have a home network and lack a DNS Server, it is preferable to set a fixed IP address for your machines.

Solutions:

1. Open the default Gitlab runner configuration file (/etc/gitlab-runner/config.toml) with your favorite editor which will look something like this:

concurrent = 1

check_interval = 0

[[runners]]

 name = "myRunner"

 url = "http://192.168.1.144/ci"

 token = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

 executor = "docker"

   [runners.docker]

   tls_verify = false

   image = "my_runner_image:latest"

   privileged = false

   disable_cache = false

   volumes = ["/cache"]

 [runners.cache]

The goal here is tell the container how to resolve my.server.com which the Gitlab runner will inject in the Docker container. Add “extra_hosts” as an extra variable in the configuration:

[[runners]]

 name = "myRunner"

 url = "http://192.168.1.144/ci"

 token = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

 executor = "docker"

   [runners.docker]

   extra_hosts = ["my.server.com:192.168.1.144"]

   tls_verify = false

   image = "my_runner_image:latest"

   privileged = false

   disable_cache = false

   volumes = ["/cache"]

 [runners.cache]

2. Gitlab runner has the concept of a pull policy of either always attempting to download the image from the registry, download if not available locally or never download. By default, it always attempts to download images so if you are trying to use an image you have built locally, it will fail. The best option is to download when not available:

[[runners]]

 name = "myRunner"

 url = "http://192.168.1.144/ci"

 token = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

 executor = "docker"

   [runners.docker]

   extra_hosts = ["my.server.com:192.168.1.144"]

   pull_policy = "if-not-present"

   tls_verify = false

   image = "my_runner_image:latest"

   privileged = false

   disable_cache = false

   volumes = ["/cache"]

 [runners.cache]

3. Create a directory in your container which you set via your Dockerfile:

RUN mkdir -p /my_build_directory

         Specify in the Gitlab runner configuration file the build directory:

           [[runners]]

 name = "myRunner"

 url = "http://192.168.1.144/ci"

 token = "xxxxxxxxxxxxxxxxxxxxxxxxxxx"

 executor = "docker"

 builds_dir = "/my_build_directory"

   [runners.docker]

   extra_hosts = ["my.server.com:192.168.1.144"]

   pull_policy = "if-not-present"

   tls_verify = false

   image = "my_runner_image:latest"

               privileged = false

   disable_cache = false

   volumes = ["/cache"]

 [runners.cache]

The code will now be checked out in /my_build_directory

If you have any questions or feedback, please do not hesitate to drop a note!