# gitlab_runner – Create, modify and delete GitLab Runners

New in version 2.8.

- Synopsis

- Requirements

- Parameters

- Notes

- Examples

- Return Values

- Status

## 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

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 / 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

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.
registration_token string / required |  | The registration token is used to register new runners.

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 | 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

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 `url` options 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.