How to Self-Host a GitLab Runner Using Docker Compose

loading views

GitLab makes it fairly easy to use our own gitlab-runner. This is useful when we run out of compute usage quota on gitlab.com or when we self-host a GitLab instance.

The former happened to me this weekend, so I wondered how hard it would be to self-host my runner. I still have a pretty underutilized ARM64 VM in Germany that was just waiting to get used.

I used docker compose to add the gitlab-runner to my server. The volumes are necessary to talk to the Docker instance from inside the container and to store the runner configuration between reboots.

# docker-compose.yaml

services:
  gitlab-runner:
    image: gitlab/gitlab-runner
    restart: always
    privileged: true
    volumes:
      - gitlab-runner-config:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock

Once we run docker compose up the container is running, and we have to register the runner on GitLab or our self-hosted instance.

We need to execute the following command inside the gitlab-runner container. We can log in to the container by running:

docker exec -it {CONTAINER_ID} sh

Inside the container we then run:

gitlab-runner register -n \
  --url "https://gitlab.com/" \
  --registration-token {TOKEN} \
  --executor docker \
  --description "ARM64" \
  --tag-list "docker, arm64" \
  --docker-image "docker:29-cli" \
  --docker-privileged \
  --docker-volumes "/certs/client"

That's it. After we ran this command, the runner is registered with GitLab. We just need to select it in Settings -> CI/CD -> Runner in our GitLab project settings and trigger a new pipeline.

While this setup is pretty simple I ran into the following issue whenever the runner was picking up one of my pipeline jobs:

$ docker pull $CONTAINER_TEST_IMAGE || true

failed to connect to the docker API at tcp://docker:2375: lookup docker on 46.38.252.230:53: no such host

$ docker build --cache-from $CONTAINER_TEST_IMAGE -t $CONTAINER_TEST_IMAGE .

ERROR: error during connect: Head "[http://docker:2375/_ping](http://docker:2375/_ping)": dial tcp: lookup docker on 46.38.225.230:53: no such host

I was able to fix this by setting the container to be privileged: true and using the --docker-privileged in the gitlab-runner register command.