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

Note

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

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

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

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

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	ref_protected ← not_protected	Determines if a runner can pick up jobs from protected branches.
active boolean	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	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	no ← yes	Searches only runners available to the user when searching for existing, when false admin token required.
registration_token string / required		The registration token is used to register new runners.
run_untagged boolean	no yes ←	Run untagged jobs or not.
state string	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	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)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/general/gitlab_runner_module.html