How to Run GitLab Runner in Docker

(the post is automatically translated by AI)

Introduction

While you can run a GitLab Runner installed directly on your machine, GitLab also provides Docker images [[1]] that let you run GitLab Runner inside a Docker container.

This article follows the official documentation [[2]] — starting with installing Docker, then creating a container, and finally running GitLab Runner inside it.

Installing Docker

macOS

$ brew cask install docker

Linux (Ubuntu) [[3]]

If this is your first Docker installation:

Update apt and allow it to use a repository over HTTPS:

$ sudo apt-get update
$ sudo apt-get install \
        ca-certificates \
        curl \
        gnupg \
        lsb-release

Add Docker’s official GPG key:

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyring.gpg

Set up the stable repository (you can substitute stable with nightly or test):

$ echo \
    "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine:

Update apt and install Docker Engine and containerd:

$ sudo apt-get update
$ sudo apt-get install docker-ce docker-ce-cli containerd.io

Verify the installation with hello-world:
```
$ sudo docker run hello-world
```

Uninstall Docker Engine:

Remove the packages:

$ sudo apt-get purge docker-ce docker-ce-cli containerd.io

Manually remove images, containers, volumes, and config files:

$ sudo rm -rf /var/lib/docker
$ sudo rm -rf /var/lib/containerd

Running GitLab Runner in a Container

Use docker run to both create and start the container in one step. Two options are available to ensure the GitLab Runner config persists across container restarts:

Option 1: Mount a local system volume

$ docker run -d --name gitlab-runner --restart always \
        -v /srv/gitlab-runner/config:/etc/gitlab-runner \
        -v /var/run/docker.sock:/var/run/docker.sock \
        gitlab/gitlab-runner:latest

Option 2: Use a Docker volume

Create a Docker volume:

$ docker volume create gitlab-runner-config

Start the runner using that volume:

$ docker run -d --name gitlab-runner --restart always \
        -v /var/run/docker.sock:/var/run/docker.sock \
        -v gitlab-runner-config:/etc/gitlab-runner \
        gitlab/gitlab-runner:latest

With either option, GitLab Runner is now running inside Docker.

Additional Notes

Updating the container after editing config.toml:
```
$ docker restart gitlab-runner
```
config.toml is typically found at the location configured when mounting (e.g., /srv/gitlab-runner/config/ for Option 1).
Reading GitLab Runner logs:
```
$ docker logs [container name]
```

Introduction#

Installing Docker#

macOS#

Linux (Ubuntu) [[3]]#

Running GitLab Runner in a Container#

Additional Notes#

References#