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

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