Shared runner configuration

Parts of the configuration are generic across all runners, this includes configuration of runner tokens and the concurrency level for example.

Shared required Ansible settings

The only required parameter in Ansible is the GitLab Runner token. For details on how to create these, and why choosing the correct scope is important, please refer to the Upstream runner scope documentation.

For GitLab versions older than 16.0, you must manually convert the registration token to a permanent runner token before setting it in Ansible. For GitLab 16.0 and later, you can simply put the token the UI or API returns in Ansible directly.

When you have your runner token, you can set it on the runner(s) you require it to be used on. Ensure the name(s) of the instance(s) below match the configured names in Terraform. The example below is the minimum requirement for enabling a runner.

In ansible/sensitive_vars.yml add the following to assign the token to a runner:

all:
  hosts:
    cluster-prefix-autoscaling-runner-small:
      gitlab_runner_token: "vae9shohKu9hieri4ahh8diZ"  # Random generated token for example, not actually usable.

    cluster-prefix-dedicated-runner-medium:
      gitlab_runner_token: "bAe6shohKu6daari4ahh69iS"  # Random generated token for example, not actually usable.

Ensure you replace cluster-prefix with the actual value of all:vars:prefix. The result should match the name the EC2 machine has in AWS, and the name of the machine in the Ansible inventory.

Note: if you remove the machine you configured, and you keep these variables configured, Ansible will re-add the host to your inventory, causing all sorts of issues since the facts cannot be resolved (since the host does not actually exist).

Shared optional Ansible settings

Most of the configuration values below map to entries in GitLab Runners config.toml. For extended information on these values, please refer to the upstream docs: GitLab Runner - Advanced Configuration.

On the Ansible side of things, there are multiple basic settings that can be customized:

Name	Default	Description
gitlab_runner_version	""	Defaults to latest version when empty
gitlab_runner_check_interval	0	Time between requests for jobs from GitLab
gitlab_runner_concurrency	2	Amount of jobs to run in parallel (total)
gitlab_runner_output_limit	10240	Maximum job log size (in bytes)
gitlab_runner_token	""	Permanent token used to talk to GitLab
gitlab_runner_tokens	[]	A list of tokens when multiple tokens are used

Note: gitlab_runner_tokens automatically includes gitlab_runner_token and deduplicates the result. For configuration clarity, it's not recommended to use both (even though you can). A seperate [[runners]] section is rendered to the configuration file for each token present.

Shared optional advanced Ansible settings

Advanced settings are also available. Some of these override cluster defaults or change internal parameters, please ensure you know what you are doing before changing these.

The following variables can be overridden, but have sane auto-calculated defaults set. In most cases, you can leave these as-is:

Name	Default	Description
gitlab_runner_name	"{{ ansible_hostname }}"	The name of the runner. Only used as identifier in logs
gitlab_runner_url	"{{ external_url_sanitised }}"	URL that GitLab is reachable on
gitlab_runner_shared_cache_bucket_name	"{{ gitlab_object_storage_prefix }}-runner-cache"	This must match up with the Terraform values
gitlab_runner_shared_cache_bucket_location	"{{ aws_region }}"	The region the bucket is in

Shared optional Ansible settings for Docker executors

The variables below are specific to Docker-style executors, which includes the Docker and Docker-Autoscale executors. The Docker executor is the default executor for Dedicated runners, and the Docker-Autoscale executor is the default executor for Autoscaling runners.

Name	Default	Description
gitlab_runner_docker_disable_cache	false	Sets disable_cache in [[runners.docker]]
gitlab_runner_docker_environment	{}	Sets environment in [[runners.docker.services]]
gitlab_runner_docker_image	"debian:stable"	Sets image in [[runners.docker]]
gitlab_runner_docker_needs_host_docker	false	Mounts /var/run/docker.sock in containers
gitlab_runner_docker_needs_kvm	false	Mounts /dev/kvm in containers
gitlab_runner_docker_privileged	false	Sets privileged in [[runners.docker]]
gitlab_runner_docker_shm_size	0	Sets shm_size in [[runners.docker]]
gitlab_runner_docker_tls_verify	false	Sets tls_verify in [[runners.docker]]
gitlab_runner_docker_volumes	[]	Populates volumes in [[runners.docker]]