W3cubDocs

/Ansible

community.general.gitlab_runners – Ansible dynamic inventory plugin for 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_runners.

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 controller node that executes this inventory.

  • python >= 2.7
  • python-gitlab > 1.8.0

Parameters

Parameter Choices/Defaults Configuration Comments
api_token
string
env:GITLAB_API_TOKEN
added in 1.0.0 of community.general
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
env:GITLAB_FILTER
added in 1.0.0 of community.general
filter runners from GitLab API
groups
dictionary
Default:
{}
Add hosts to group based on Jinja2 conditionals.
keyed_groups
list / elements=string
Default:
[]
Add hosts to group based on the values of a variable.
leading_separator
boolean
added in 2.11 of ansible.builtin
    Choices:
  • no
  • yes ←
Use in conjunction with keyed_groups.
By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
This is because the default prefix is "" and the default separator is "_".
Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
If the group name is derived from a mapping the separator is still used to concatenate the items.
To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
plugin
string / required
    Choices:
  • gitlab_runners
  • community.general.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"
env:GITLAB_SERVER_URL
added in 1.0.0 of community.general
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.
use_extra_vars
boolean
added in 2.11 of ansible.builtin
    Choices:
  • no ←
  • yes
ini entries:

[inventory_plugins]
use_extra_vars = no

env:ANSIBLE_INVENTORY_USE_EXTRA_VARS
Merge extra vars into the available variables for composition (highest precedence).
verbose_output
boolean
    Choices:
  • no
  • yes ←
Toggle to (not) include all available nodes metadata

Examples

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

# Example using constructed features to create groups and set ansible_host
plugin: community.general.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

Authors

© 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_runners_inventory.html