community.general.gitlab_runner module – Create, modify and delete GitLab Runners
Note
This module is part of the community.general collection (version 8.6.4).
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
Register, update and delete runners on GitLab Server side 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 and https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user.
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/.
This module does not handle the
gitlab-runner
process part, but only manages the runner on GitLab Server side through its API. Once the module has created the runner, you may use the generated token to rungitlab-runner register
command
Aliases: source_control.gitlab.gitlab_runner
Requirements
The below requirements are needed on the host that executes this module.
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 If set to If set to Before community.general 8.0.0 the default was Choices:
|
|
Whether the runner should be registered with an access level or not. If set to If set to The default of this option changed to Choices:
|
|
Define if the runners is immediately active after creation. Mutually exclusive with 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 CA certificates bundle to use to verify GitLab server certificate. |
|
The unique name of the runner. |
|
ID or full path of the group in the form group/subgroup. Mutually exclusive with Must be group’s numeric ID if |
|
Determines if the runner is locked or not. Choices:
|
|
The maximum time that a runner has to complete a specific job. Default: |
|
Define if the runners is active or paused after creation. Mutually exclusive with Choices:
|
|
ID or full path of the project in the form of group/name. Mutually exclusive with Mutually exclusive with Must be project’s numeric ID if |
|
The registration token is used to register new runners before GitLab 16.0. Required if If set, the runner will be created using the old runner creation workflow. If not set, the runner will be created using the new runner creation workflow, introduced in GitLab 16.0. If not set, requires python-gitlab >= 4.0.0. |
|
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:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: full |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
Notes
Note
To create a new runner at least the
api_token
,description
andapi_url
options are required.Runners need to have unique descriptions, since this attribute is used as key for idempotency
Examples
- name: Create an instance-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: Create a group-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
group: top-level-group/subgroup
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: Create a project-level runner
community.general.gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
state: present
active: true
tag_list: ['docker']
run_untagged: false
locked: false
project: top-level-group/subgroup/project
register: runner # Register module output to run C(gitlab-runner register) command in another task
- name: "Register instance-level runner with registration token (deprecated)"
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
register: runner # Register module output to run C(gitlab-runner register) command in another task
- 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 a project-level runner with registration token (deprecated)"
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
register: runner # Register module output to run C(gitlab-runner register) command in another task
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: |
|
Success or failure message Returned: always Sample: |
|
json parsed response from the server Returned: always |
|
API object Returned: always |