Skip to content

Instance runners

gitlab_settings_runners is a list of instance runner entries keyed by description. Each entry registers a runner through GitLab's user-runner endpoint (GitLab 16+), converges its attributes, and supports deletion. Managing runners requires an administrator credential.

The authentication token is returned exactly once

GitLab returns a runner's authentication token only in the creation response; it is unrecoverable afterwards. Declare token_file to capture it — the token is written to that absolute controller-side path with owner-only permissions (0600) at registration time, and only then. Reruns of an already-registered runner never touch the file. Pass the captured token to your runner installation (for example gitlab-runner run with the glrt- token).

Example

gitlab_settings_runners:
  - description: bootstrap-runner
    token_file: /var/lib/ansible/secrets/bootstrap-runner.token
    tag_list:
      - bootstrap
      - linux
    runner:
      run_untagged: true
      paused: false
  - description: retired-runner
    state: absent

Runner Entry Spec

description string Required

The runner's natural identity. GitLab's numeric id is resolved through the admin runners list, scoped to instance runners; a duplicate description is a named failure rather than a guess.

 Example: 
gitlab_settings_runners:
  - description: bootstrap-runner
...

state string 

Runner-entry lifecycle.

Can be one of: present, absent

Default: present

 Example: 
gitlab_settings_runners:
  - description: retired-runner
    state: absent
...

token_file string (absolute path) 

Controller path receiving the one-time authentication token at registration.

 Example: 
gitlab_settings_runners:
  - description: bootstrap-runner
    token_file: /var/lib/ansible/secrets/bootstrap-runner.token
...

tag_list array of strings 

Runner tags, reconciled against the live tag list.

Values of tag_list

 Each item is a non-empty tag string. Order does not affect the runner's tag membership.

 Example: 
gitlab_settings_runners:
  - description: bootstrap-runner
    tag_list: [bootstrap, linux]
...

runner object 

Runner attributes. Comparison reads the runner-detail endpoint because the admin list omits managed fields. Registration is fixed to instance runners (runner_type: instance_type).

Properties of runner

 paused boolean

 locked boolean

 run_untagged boolean

 access_level string

  Can be one of: not_protected, ref_protected.

 maintenance_note string

 maximum_timeout integer

 Example: 
gitlab_settings_runners:
  - description: bootstrap-runner
    runner:
      run_untagged: true
      paused: false
...

Group and project runners

Group and project runners are declared where their owner lives: a runners list under a group or project entry. Each entry uses the same registration machinery as instance runners — creation goes through the user-runner endpoint (GitLab resolves the declared parent to its numeric id automatically), the one-time authentication token is captured to a declared token_file (mode 0600, absolute path), and comparison reads the runner-detail endpoint. Entries are flat: identity is description, lifecycle is state (present/absent), and runner attributes (paused, locked, run_untagged, access_level, maintenance_note, maximum_timeout, tag_list) sit beside them.

gitlab_settings_groups:
  - name: platform
    path: platform
    runners:
      - description: platform-group-runner
        token_file: /var/lib/ansible/secrets/platform-runner-token
        run_untagged: true

gitlab_settings_projects:
  - name: service
    path: service
    namespace: platform
    runners:
      - description: service-project-runner
        tag_list: [deploy]
        access_level: ref_protected

The listing that drives convergence is scoped to the declared parent and filtered to its runner type, so runners inherited from ancestor groups or shared from other scopes are never claimed or removed.