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

Note

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

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 from protected 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 timeout that a runner has to pick up 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.
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

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)