gitlab-runner

What is gitlab-runner?

The GitLab Runner image packages GitLab Runner, the open-source agent used to run jobs defined in .gitlab-ci.yml pipelines. It connects to a GitLab instance, polls for pending jobs, and executes them in various executors such as Docker, Kubernetes, virtual machines, or directly on the host system.

GitLab Runner is essential for enabling GitLab CI/CD. It can run build, test, and deployment tasks in a repeatable and isolated way, making it a core component of automated software delivery pipelines.

The containerized GitLab Runner image simplifies setup and scaling, allowing operators to deploy runners quickly in Kubernetes clusters, Docker environments, or cloud infrastructure.

How to use this image

The GitLab Runner image can be run locally or as a service in Kubernetes.

Examples:

<code># Register a new runner with your GitLab instance
docker run --rm -it \\
 -v /srv/gitlab-runner/config:/etc/gitlab-runner \\
 gitlab/gitlab-runner register</code>

<code># Run the GitLab Runner
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</code>

<code># Check version
docker run --rm gitlab/gitlab-runner --version</code>

In Kubernetes, GitLab Runner can be deployed with the official Helm chart for cluster-wide CI/CD execution.

Image variants

The GitLab Runner image is generally published under gitlab/gitlab-runner and available in these forms:

gitlab/gitlab-runner:<version>

Version-pinned images (e.g., gitlab/gitlab-runner:v17.4.0) recommended for production to ensure reproducibility.

gitlab/gitlab-runner:latest

Tracks the most recent stable release. Convenient for testing but not ideal for production use.

gitlab/gitlab-runner:alpine

A lightweight variant built on Alpine Linux. Smaller size, but with musl libc instead of glibc, which may affect compatibility with some integrations.