community.general.gitlab_runner module – Create, modify and delete GitLab Runners.
Note
This module is part of the community.general collection (version 4.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
.
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://%24GITLAB_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://%24GITLAB_URL/admin/runners/.
Requirements
The below requirements are needed on the host that executes this module.
python >= 2.7
python-gitlab >= 1.5.0
requests (Python library https://pypi.org/project/requests/)
Parameters
Parameter |
Comments |
---|---|
Determines if a runner can pick up jobs only from protected branches. If set to If set to Choices:
|
|
Define if the runners is immediately active after creation. Choices:
|
|
GitLab CI job token for logging in. |
|
GitLab OAuth token for logging in. |
|
The password to use for authentication against the API |
|
GitLab access token with API permissions. |
|
The resolvable endpoint for the API |
|
The username to use for authentication against the API |
|
The unique name of the runner. |
|
Determines if the runner is locked or not. Choices:
|
|
The maximum time that a runner has to complete a specific job. Default: 3600 |
|
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:
|
|
ID or full path of the project in the form of group/name. Mutually exclusive with owned since community.general 4.5.0. |
|
The registration token is used to register new runners. Required if state is |
|
Run untagged jobs or not. Choices:
|
|
Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name. Choices:
|
|
The tags that apply to the runner. Default: [] |
|
Whether or not to validate SSL certs when supplying a https endpoint. Choices:
|
Notes
Note
To create a new runner at least the
api_token
,description
andapi_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 |
Description |
---|---|
the error message returned by the GitLab API Returned: failed Sample: “400: path is already in use” |
|
Success or failure message Returned: always Sample: “Success” |
|
json parsed response from the server Returned: always |
|
API object Returned: always |
Authors
Samy Coenen (@SamyCoenen)
Guillaume Martinez (@Lunik)
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication