gitlab-runner on docker

Use this template to start your own gitlab-runner on docker.

Setup

1. Configure environment variables (optional):

   cp env.example .env
   # Edit .env to set GITLAB_RUNNER_VERSION if needed
   

2. Configure the runner: Either use the included ./config/config.toml.example and copy it to ./config/config.toml or create your own. By default the container should create a new config.toml file in the ./config directory if it is not present.

3. Register the runner (if using your own config.toml or the default creation): Start the container and attach a shell in the container and run the gitlab-runner register --url https://gitlab.example.com --token your-secret-token command and follow the instructions.

4. Start the runner:

   docker compose up -d
   

If you use docker in docker, make sure to add /var/run/docker.sock:/var/run/docker.sock in your ./config/config.toml, e.g.

# ...
[[runners]]
  name = "runner on stefan-workstation"
  url = "https://gitlab.example.com"
  # ...
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    MaxUploadedArchiveSize = 0
  [runners.docker]
    # ...
    volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"]
    # ...
  [runners.feature_flags]
    FF_NETWORK_PER_BUILD = true

Important: The FF_NETWORK_PER_BUILD = true feature flag is required when using Docker 29+ or newer GitLab Runner versions to avoid the deprecated container linking mechanism. This flag enables per-job Docker networks instead of using the deprecated --link feature. For more information, see the GitLab Runner Docker Executor documentation.

Configuration Files

• compose.yml - Docker Compose configuration file (modern naming, no version field)
• env.example - Example environment variables file (copy to .env to customize)
• config/config.toml.example - Example GitLab Runner configuration