About ansible-gitlab-runner

Ansible role to install gitlab-runner

r

Published by

README.md

GitLab Runner

This role will install the official GitLab Runner (fork from haroldb) with updates. Needed something simple and working, this did the trick for me. Open for changes though.

Requirements

This role requires:

Ansible 2.13 or higher
Installed Ansible Galaxy collections listed in file requirements.yml

Role Variables

gitlab_runner_package_name - As of GitLab 10.x, the package name gitlab-ci-multi-runner has been renamed to gitlab-runner. To install a version earlier than 10.x, define the variable gitlab_runner_package_name: gitlab-ci-multi-runner.
gitlab_runner_wanted_version or gitlab_runner_package_version - Use these to install a specific version of the GitLab Runner (by default, the latest version is installed).
- On macOS and Windows, use gitlab_runner_wanted_version: 12.4.1 (example).
- On Linux, use gitlab_runner_package_version instead.
gitlab_runner_macos_install_from_homebrew - macOS-only switch to install/upgrade GitLab Runner via Homebrew instead of downloading from gitlab_runner_download_url (default: false).
- When installing via brew, gitlab_runner_wanted_version is currently ignored.
gitlab_runner_concurrent - Defines the maximum number of jobs that can run concurrently. Defaults to the number of processor cores.
gitlab_runner_registration_token - The GitLab registration token. If specified, this will register each runner with a GitLab server. Note: This token can only be used globally if gitlab_runner_registration_token_type is set to the deprecated registration-token. Otherwise, you must specify a token for each item in gitlab_runner_runners, as shown in the example playbook below. This token is deprecated in GitLab version 16.0 and will be removed in version 18.0.
gitlab_runner_registration_token_type - Specifies the type of registration token to use for GitLab Runner registration:
- Set to "authentication-token" to register the runner with the --token option (following the new workflow: https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html).
- Set to "registration-token" to register the runner with the --registration-token option. This is deprecated in GitLab 16.0 but remains usable until it is removed in version 18.0.
- For GitLab version 16.0 and above, it is recommended to specify a token for each runner in the gitlab_runner_runners section and set this variable to "authentication-token".
gitlab_runner_coordinator_url - The GitLab coordinator URL. Defaults to https://gitlab.com.
gitlab_runner_sentry_dsn - Enables tracking of system-level errors to Sentry.
gitlab_runner_listen_address - Enables the /metrics endpoint for Prometheus scraping.
gitlab_runner_runners - A list of GitLab runners to register and configure. By default, this is set to a single shell executor.
gitlab_runner_skip_package_repo_install - Skips the installation of the APT or YUM repository (default: false). You should ensure that the necessary packages are available in your repository before running this role.
gitlab_runner_keyring_path - Path to the GitLab Runner repository GPG keyring file (default: /etc/apt/keyrings/runner_gitlab-runner-archive-keyring.gpg).
- Set to /etc/apt/keyrings/runner_gitlab-runner-archive-keyring.gpg (default) if using APT > 1.1
- Set to /etc/apt/trusted.gpg.d/runner_gitlab-runner.gpg if using legacy APT < 1.1)
- Set to custom path if you expect a different location for the keyring
gitlab_runner_config_update_mode - Defines how configuration updates are applied:
- Set to by_config_toml (default) to apply configuration changes directly by updating the config.toml file.
- Set to by_registering if changes should be applied by unregistering and re-registering the runner when configuration changes.
- Set to by_template if changes for all runners should directly be written in the config.toml file. This method is faster than by_config_toml. From the original config.toml it reads only 3 fields per runner: id, token_obtained_at and token_expires_at. All other content from the file is ignored
gitlab_unregister_runner_executors_which_are_not_longer_configured - Set to true if executors should be unregistered from a runner when they are no longer configured in Ansible. Default: false.

See the defaults/main.yml file for a list of all possible options that can be passed to a runner registration command.

Gitlab Runners cache

For each gitlab runner in gitlab_runner_runners you can set cache options. At the moment role support s3, azure and gcs types. Example configurration for s3 can be:

gitlab_runner:
  cache_type: "s3"
  cache_path: "cache"
  cache_shared: true
  cache_s3_server_address: "s3.amazonaws.com"
  cache_s3_access_key: "<access_key>"
  cache_s3_secret_key: "<secret_key>"
  cache_s3_bucket_name: "<bucket_name>"
  cache_s3_bucket_location: "eu-west-1"
  cache_s3_insecure: false

Autoscale Runner Machine vars for AWS (optional)

MachineOptions: [] - Foremost you need to pass an array of dedicated vars in the machine_options to configure your scaling runner:
- amazonec2-access-key and amazonec2-secret-key the keys of the dedicated IAM user with permission for EC2
- amazonec2-zone
- amazonec2-region
- amazonec2-vpc-id
- amazonec2-subnet-id
- amazonec2-use-private-address=true
- amazonec2-security-group
- amazonec2-instance-type
- you can also set amazonec2-tags to identify you instance more easily via aws-cli or the console.
MachineDriver - which should be set to amzonec2 when working on AWS
MachineName - Name of the machine. It must contain %s, which will be replaced with a unique machine identifier.
IdleCount - Number of machines, that need to be created and waiting in Idle state.
IdleTime - Time (in seconds) for machine to be in Idle state before it is removed.
MaxGrowthRate - The maximum number of machines that can be added to the runner in parallel. Default is 0 (no limit).
MaxBuilds - Maximum job (build) count before machine is removed.
IdleScaleFactor - (Experimental) The number of Idle machines as a factor of the number of machines currently in use. Must be in float number format. See the autoscale documentation for more details. Defaults to 0.0.
IdleCountMin - Minimal number of machines that need to be created and waiting in Idle state when the IdleScaleFactor is in use. Default is 1.

Read Sources

For details follow these links:

See the config for more options

Example Playbook

- hosts: all
  become: true
  vars_files:
    - vars/main.yml
  roles:
    - { role: riemers.gitlab-runner }

Inside vars/main.yml

gitlab_runner_coordinator_url: https://gitlab.com
gitlab_runner_registration_token: '12341234'
gitlab_runner_runners:
  - name: 'Example Docker GitLab Runner'
    # token is an optional override to the global gitlab_runner_registration_token
    token: 'abcd'
    # url is an optional override to the global gitlab_runner_coordinator_url
    url: 'https://my-own-gitlab.mydomain.com'
    request_concurrency: 2
    executor: docker
    docker_image: 'alpine'
    tags:
      - node
      - ruby
      - mysql
    docker_volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "/cache"
    extra_configs:
      runners.docker:
        memory: 512m
        allowed_images: ["ruby:*", "python:*", "php:*"]
      runners.docker.sysctls:
        net.ipv4.ip_forward: "1"

autoscale setup on AWS

how vars/main.yml would look like, if you setup an autoscaling GitLab-Runner on AWS:

gitlab_runner_registration_token: 'HUzTMgnxk17YV8Rj8ucQ'
gitlab_runner_coordinator_url: 'https://gitlab.com'
gitlab_runner_runners:
  - name: 'Example autoscaling GitLab Runner'
    state: present
    # token is an optional override to the global gitlab_runner_registration_token
    token: 'HUzTMgnxk17YV8Rj8ucQ'
    executor: 'docker+machine'
    # Maximum number of jobs to run concurrently on this specific runner.
    # Defaults to 0, simply means don't limit.
    concurrent_specific: '0'
    docker_image: 'alpine'
    # Indicates whether this runner can pick jobs without tags.
    run_untagged: true
    machine_IdleCount: 1
    machine_IdleTime: 1800
    machine_MaxBuilds: 10
    machine_MachineDriver: 'amazonec2'
    machine_MachineName: 'git-runner-%s'
    machine_MachineOptions: ["amazonec2-access-key={{ lookup('env','AWS_IAM_ACCESS_KEY') }}", "amazonec2-secret-key={{ lookup('env','AWS_IAM_SECRET_KEY') }}", "amazonec2-zone={{ lookup('env','AWS_EC2_ZONE') }}", "amazonec2-region={{ lookup('env','AWS_EC2_REGION') }}", "amazonec2-vpc-id={{ lookup('env','AWS_VPC_ID') }}", "amazonec2-subnet-id={{ lookup('env','AWS_SUBNET_ID') }}", "amazonec2-use-private-address=true", "amazonec2-tags=gitlab-runner", "amazonec2-security-group={{ lookup('env','AWS_EC2_SECURITY_GROUP') }}", "amazonec2-instance-type={{ lookup('env','AWS_EC2_INSTANCE_TYPE') }}"]
    machine_autoscaling:
      - Periods: ["* * 7-18 * * mon-fri *"]
        Timezone: "UTC"
        IdleCount: 3
        IdleTime: 900
      - Periods: ["* * * * * sat,sun *"]
        Timezone: "UTC"
        IdleCount: 0
        IdleTime: 300

NOTE

from https://docs.gitlab.com/runner/executors/docker_machine.html:

The first time you’re using Docker Machine, it’s best to execute manually docker-machine create... with your chosen driver and all options from the MachineOptions section. This will set up the Docker Machine environment properly and will also be a good validation of the specified options. After this, you can destroy the machine with docker-machine rm [machine_name] and start the Runner.

Example:


docker-machine rm test

Testing

CI uses the current Ansible role testing pattern: a fast lint gate, then Molecule integration tests in Docker on Linux.

Every pull request and push to master runs:

ansible-lint (static analysis)
Molecule scenarios in Docker:
- default — install runner, register against a mock GitLab API, verify config.toml
- config-update — verify configuration updates are applied correctly

A weekly scheduled run catches upstream image and dependency regressions.

Linux package installation is covered thoroughly in CI. macOS and Windows task files are linted and reviewed, but are not installed on native GitHub runners each push — that Travis-era approach is slow, flaky, and no longer common for Ansible roles.

Run the same checks locally before pushing:

# Linux or WSL (recommended)
bash scripts/local-ci.sh

# Windows PowerShell (lint via Docker; Molecule via WSL)
./scripts/local-ci.ps1

Use --skip-molecule / -SkipMolecule when Docker is unavailable.

Run As A Different User

To run the Gitlab Runner as a different user (rather than the default gitlab-runner user), there is a workaround requiring a little extra Ansible to be run. See https://github.com/riemers/ansible-gitlab-runner/issues/277 for details.

Contributors

Feel free to add your name to the readme if you make a PR. A full list of people from the PR's is here

Gastrofix for adding Mac Support
Matthias Schmieder for adding Windows Support
dniwdeus & rosenstrauch for adding AWS autoscale option
oscillate123 for fixing Windows config.toml idempotency
cchaudier for fixing changing the version of a package which is on the apt hold list

ansible-gitlab-runner