community.general.gitlab_runner module – Create, modify and delete GitLab Runners

Note

This module is part of the community.general collection (version 5.8.3).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.gitlab_runner.

Synopsis

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

access_level

string

Determines if a runner can pick up jobs only from protected branches.

If set to ref_protected, runner can pick up jobs only from protected branches.

If set to not_protected, runner can pick up jobs from both protected and unprotected branches.

Choices:

  • "ref_protected" ← (default)

  • "not_protected"

active

boolean

Define if the runners is immediately active after creation.

Choices:

  • false

  • true ← (default)

api_job_token

string

added in community.general 4.2.0

GitLab CI job token for logging in.

api_oauth_token

string

added in community.general 4.2.0

GitLab OAuth token for logging in.

api_password

string

The password to use for authentication against the API

api_token

string

GitLab access token with API permissions.

api_url

string

The resolvable endpoint for the API

api_username

string

The username to use for authentication against the API

description

aliases: name

string / required

The unique name of the runner.

locked

boolean

Determines if the runner is locked or not.

Choices:

  • false ← (default)

  • true

maximum_timeout

integer

The maximum time that a runner has to complete a specific job.

Default: 3600

owned

boolean

added in community.general 2.0.0

Searches only runners available to the user when searching for existing, when false admin token required.

Mutually exclusive with project since community.general 4.5.0.

Choices:

  • false ← (default)

  • true

project

string

added in community.general 3.7.0

ID or full path of the project in the form of group/name.

Mutually exclusive with owned since community.general 4.5.0.

registration_token

string

The registration token is used to register new runners.

Required if state is present.

run_untagged

boolean

Run untagged jobs or not.

Choices:

  • false

  • true ← (default)

state

string

Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name.

Choices:

  • "present" ← (default)

  • "absent"

tag_list

list / elements=string

The tags that apply to the runner.

Default: []

validate_certs

boolean

Whether or not to validate SSL certs when supplying a https endpoint.

Choices:

  • false

  • true ← (default)

Notes

Note

  • To create a new runner at least the api_token, description and api_url options are required.

  • Runners need to have unique descriptions.

Examples

- name: "Register runner"
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    registration_token: 4gfdsg345
    description: Docker Machine t1
    state: present
    active: true
    tag_list: ['docker']
    run_untagged: false
    locked: false

- name: "Delete runner"
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    description: Docker Machine t1
    state: absent

- name: Delete an owned runner as a non-admin
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    description: Docker Machine t1
    owned: true
    state: absent

- name: Register runner for a specific project
  community.general.gitlab_runner:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    registration_token: 4gfdsg345
    description: MyProject runner
    state: present
    project: mygroup/mysubgroup/myproject

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

error

string

the error message returned by the GitLab API

Returned: failed

Sample: "400: path is already in use"

msg

string

Success or failure message

Returned: always

Sample: "Success"

result

dictionary

json parsed response from the server

Returned: always

runner

dictionary

API object

Returned: always

Authors

  • Samy Coenen (@SamyCoenen)

  • Guillaume Martinez (@Lunik)