W3cubDocs

/Ansible

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

Note

This module is part of the community.general collection (version 10.7.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. 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
Requirements
Parameters
Attributes
Notes
Examples
Return Values

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 run gitlab-runner register command.

Requirements

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

python-gitlab >= 1.5.0 for legacy runner registration workflow (runner registration token - https://docs.gitlab.com/runner/register/#register-with-a-runner-registration-token-deprecated)
python-gitlab >= 4.0.0 for new runner registration workflow (runner authentication token - https://docs.gitlab.com/runner/register/#register-with-a-runner-authentication-token)
requests (Python library https://pypi.org/project/requests/)

Parameters

Parameter	Comments
access_level string	Determines if a runner can pick up jobs only from protected branches. If `access_level_on_creation` is not explicitly set to `true`, this option is ignored on registration and is only applied on updates. If set to `not_protected`, runner can pick up jobs from both protected and unprotected branches. If set to `ref_protected`, runner can pick up jobs only from protected branches. Before community.general 8.0.0 the default was `ref_protected`. This was changed to no default in community.general 8.0.0. If this option is not specified explicitly, GitLab uses `not_protected` on creation, and the value set is not changed on any updates. Choices: `"not_protected"` `"ref_protected"`
access_level_on_creation boolean added in community.general 6.3.0	Whether the runner should be registered with an access level or not. If set to `true`, the value of `access_level` is used for runner registration. If set to `false`, GitLab registers the runner with the default access level. The default of this option changed to `true` in community.general 7.0.0. Before, it was `false`. Choices: `false` `true` ← (default)
active boolean	Define if the runners is immediately active after creation. Mutually exclusive with `paused`. Choices: `false` `true` ← (default)
api_job_token string added in community.general 4.2.0	GitLab CI job token for logging in.
api_oauth_token string added in community.general 4.2.0	GitLab OAuth token for logging in.
api_password string	The password to use for authentication against the API.
api_token string	GitLab access token with API permissions.
api_url string	The resolvable endpoint for the API.
api_username string	The username to use for authentication against the API.
ca_path string added in community.general 8.1.0	The CA certificates bundle to use to verify GitLab server certificate.
description aliases: name string / required	The unique name of the runner.
group string added in community.general 6.5.0	ID or full path of the group in the form group/subgroup. Mutually exclusive with `owned` and `project`. Must be group’s numeric ID if `registration_token` is not set and `state=present`.
locked boolean	Determines if the runner is locked or not. Choices: `false` ← (default) `true`
maximum_timeout integer	The maximum time that a runner has to complete a specific job. Default: `3600`
owned boolean added in community.general 2.0.0	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. Mutually exclusive with `group`. Choices: `false` ← (default) `true`
paused boolean added in community.general 8.1.0	Define if the runners is active or paused after creation. Mutually exclusive with `active`. Choices: `false` ← (default) `true`
project string added in community.general 3.7.0	ID or full path of the project in the form of group/name. Mutually exclusive with `owned` since community.general 4.5.0. Mutually exclusive with `group`. Must be project’s numeric ID if `registration_token` is not set and `state=present`.
registration_token string	The registration token is used to register new runners before GitLab 16.0. Required if `state=present` for GitLab < 16.0. If set, the runner is created using the old runner creation workflow. If not set, the runner is created using the new runner creation workflow, introduced in GitLab 16.0. If not set, requires python-gitlab >= 4.0.0.
run_untagged boolean	Run untagged jobs or not. Choices: `false` `true` ← (default)
state string	Make sure that the runner with the same name exists with the same configuration or delete the runner with the same name. Choices: `"present"` ← (default) `"absent"`
tag_list list / elements=string	The tags that apply to the runner. Default: `[]`
validate_certs boolean	Whether or not to validate SSL certs when supplying a HTTPS endpoint. Choices: `false` `true` ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

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, 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
error string	The error message returned by the GitLab API. Returned: failed Sample: `"400: path is already in use"`
msg string	Success or failure message. Returned: always Sample: `"Success"`
result dictionary	JSON-parsed response from the server. Returned: always
runner dictionary	API object. Returned: always

Authors

Samy Coenen (@SamyCoenen)
Guillaume Martinez (@Lunik)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 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