community.general.gitlab_project_variable – Creates/updates/deletes GitLab Projects Variables

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

Synopsis

  • When a project variable does not exist, it will be created.
  • When a project variable does exist, its value will be updated when the values are different.
  • Variables which are untouched in the playbook, but are not untouched in the GitLab project, they stay untouched (purge is false) or will be deleted (purge is true).

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.7
  • python-gitlab python module

Parameters

Parameter Choices/Defaults Comments
api_password
string
The password to use for authentication against the API
api_token
string / required
GitLab access token with API permissions.
api_url
string
The resolvable endpoint for the API
api_username
string
The username to use for authentication against the API
project
string / required
The path and name of the project.
purge
boolean
    Choices:
  • no ←
  • yes
When set to true, all variables which are not untouched in the task will be deleted.
state
string
    Choices:
  • present ←
  • absent
Create or delete project variable.
Possible values are present and absent.
validate_certs
boolean
    Choices:
  • no
  • yes ←
Whether or not to validate SSL certs when supplying a https endpoint.
vars
dictionary
Default:
{}
When the list element is a simple key-value pair, masked and protected will be set to false.
When the list element is a dict with the keys value, masked and protected, the user can have full control about whether a value should be masked, protected or both.
Support for protected values requires GitLab >= 9.3.
Support for masked values requires GitLab >= 11.10.
A value must be a string or a number.
Field variable_type must be a string with either env_var, which is the default, or file.
Field environment_scope must be a string defined by scope environment.
When a value is masked, it must be in Base64 and have a length of at least 8 characters. See GitLab documentation on acceptable values for a masked variable (https://docs.gitlab.com/ce/ci/variables/#masked-variables).

Examples

- name: Set or update some CI/CD variables
  community.general.gitlab_project_variable:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: markuman/dotfiles
    purge: false
    vars:
      ACCESS_KEY_ID: abc123
      SECRET_ACCESS_KEY: 321cba

- name: Set or update some CI/CD variables
  community.general.gitlab_project_variable:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: markuman/dotfiles
    purge: false
    vars:
      ACCESS_KEY_ID: abc123
      SECRET_ACCESS_KEY:
        value: 3214cbad
        masked: true
        protected: true
        variable_type: env_var
        environment_scope: '*'

- name: Delete one variable
  community.general.gitlab_project_variable:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: markuman/dotfiles
    state: absent
    vars:
      ACCESS_KEY_ID: abc123

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
project_variable
dictionary
always
Four lists of the variablenames which were added, updated, removed or exist.
added
list / elements=string
always
A list of variables which were created.

Sample:
['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
removed
list / elements=string
always
A list of variables which were deleted.

Sample:
['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
untouched
list / elements=string
always
A list of variables which exist.

Sample:
['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']
updated
list / elements=string
always
A list of variables whose values were changed.

Sample:
['ACCESS_KEY_ID', 'SECRET_ACCESS_KEY']


Authors

  • Markus Bergholz (@markuman)

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