W3cubDocs

/Ansible

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

Note

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

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.

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	Choices: ref_protected ← not_protected	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.
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 time that a runner has to complete 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.
project string added in 3.7.0 of community.general		ID or full path of the project in the form of group/name.
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

- 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	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/latest/collections/community/general/gitlab_runner_module.html