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

Note

This plugin is part of the community.general collection (version 2.5.1).

To install it use: ansible-galaxy collection install community.general.

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

Synopsis

• Register, update and delete runners with the GitLab API.

• All operations are performed using the GitLab API v4.

• For details, consult the full API documentation at https://docs.gitlab.com/ee/api/runners.html.

• A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at https://$GITLAB_URL/profile/personal_access_tokens.

• A valid registration token is required for registering a new runner. To create shared runners, you need to ask your administrator to give you this token. It can be found at https://$GITLAB_URL/admin/runners/.

Requirements

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

• python >= 2.7

• python-gitlab >= 1.5.0

Parameters

Parameter	Choices/Defaults	Comments
access_level string	Choices: ref_protected ← not_protected	Determines if a runner can pick up jobs from protected branches.
active boolean	Choices: no yes ←	Define if the runners is immediately active after creation.
api_password string		The password to use for authentication against the API
api_token string		Your private token to interact with the GitLab API.
api_url string		The resolvable endpoint for the API
api_username string		The username to use for authentication against the API
description string / required		The unique name of the runner. aliases: name
locked boolean	Choices: no ← yes	Determines if the runner is locked or not.
maximum_timeout integer	Default: 3600	The maximum timeout that a runner has to pick up a specific job.
owned boolean added in 2.0.0 of community.general	Choices: no ← yes	Searches only runners available to the user when searching for existing, when false admin token required.
registration_token string		The registration token is used to register new runners. Required if state is present.
run_untagged boolean	Choices: no yes ←	Run untagged jobs or not.
state string	Choices: present ← absent	Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name.
tag_list list / elements=string	Default: []	The tags that apply to the runner.
validate_certs boolean	Choices: no yes ←	Whether or not to validate SSL certs when supplying a https endpoint.

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: yes
    state: absent

Return Values

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

Key	Returned	Description
error string	failed	the error message returned by the GitLab API Sample: 400: path is already in use
msg string	always	Success or failure message Sample: Success
result dictionary	always	json parsed response from the server
runner dictionary	always	API object

Authors

• Samy Coenen (@SamyCoenen)

• Guillaume Martinez (@Lunik)