# gitlab_runners – Ansible dynamic inventory plugin for GitLab runners

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Examples
- Status

## Synopsis

- Reads inventories from the GitLab API.
- Uses a YAML configuration file gitlab_runners.[yml|yaml].

## Requirements

The below requirements are needed on the local master node that executes this inventory.

- python >= 2.7
- python-gitlab > 1.8.0

## Parameters

Parameter | Choices/Defaults | Configuration | Comments
--- | --- | --- | ---
api_token string |  |  | GitLab token for logging in. aliases: private_token, access_token
compose dictionary | Default: {} |  | Create vars from jinja2 expressions.

filter
string

Choices:
- active
- paused
- online
- specific
- shared

filter runners from GitLab API

groups dictionary | Default: {} |  | Add hosts to group based on Jinja2 conditionals.
keyed_groups list | Default: [] |  | Add hosts to group based on the values of a variable.

plugin
string / required

Choices:
- gitlab_runners

The name of this plugin, it should always be set to 'gitlab_runners' for this plugin to recognize it as it's own.

server_url string / required | Default: "https://gitlab.com" |  | The URL of the GitLab server, with protocol (i.e. http or https).

strict
boolean

Choices:
- no ←
- yes

If `yes` make invalid entries a fatal error, otherwise skip and continue.
Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

verbose_output
boolean

Choices:
- no
- yes ←

Toggle to (not) include all available nodes metadata

## Examples

    # gitlab_runners.yml
    plugin: gitlab_runners
    host: https://gitlab.com

    # Example using constructed features to create groups and set ansible_host
    plugin: gitlab_runners
    host: https://gitlab.com
    strict: False
    keyed_groups:
      # add e.g. amd64 hosts to an arch_amd64 group
      - prefix: arch
        key: 'architecture'
      # add e.g. linux hosts to an os_linux group
      - prefix: os
        key: 'platform'
      # create a group per runner tag
      # e.g. a runner tagged w/ "production" ends up in group "label_production"
      # hint: labels containing special characters will be converted to safe names
      - key: 'tag_list'
        prefix: tag

## Status

- This inventory is not guaranteed to have a backwards compatible interface. [preview]
- This inventory is maintained by the Ansible Community. [community]

### Authors

- UNKNOWN

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.