gitlab_runner – Create, modify and delete GitLab Runners
New in version 2.8.
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://$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/.
Requirements
The below requirements are needed on the host that executes this module.
- python >= 2.7
- python-gitlab <= 1.12.1
Parameters
| Parameter | Choices/Defaults | Comments |
|---|---|---|
| access_level
string
|
|
Determines if a runner can pick up jobs from protected branches.
|
| active
boolean
|
|
Define if the runners is immediately active after creation.
|
| api_password
string
|
The password to use for authentication against the API
|
|
| api_token
string / required
|
Your private token to interact with the GitLab API.
aliases: private_token |
|
| 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
|
|
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.
|
| registration_token
string / required
|
The registration token is used to register new runners.
|
|
| run_untagged
boolean
|
|
Run untagged jobs or not.
|
| state
string
|
|
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
|
Default:
[]
|
The tags that apply to the runner.
|
| url
string
|
The URL of the GitLab server, with protocol (i.e. http or https).
|
|
| validate_certs
boolean
|
|
Whether or not to validate SSL certs when supplying a https endpoint.
|
Notes
Note
- To create a new runner at least the
api_token,descriptionandurloptions are required. - Runners need to have unique descriptions.
Examples
- name: "Register runner"
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"
gitlab_runner:
api_url: https://gitlab.example.com/
api_token: "{{ access_token }}"
description: Docker Machine t1
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
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Samy Coenen (@SamyCoenen)
- Guillaume Martinez (@Lunik)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/gitlab_runner_module.html