community.general.gitlab_label module – Creates/updates/deletes GitLab Labels belonging to project or group.

Note

This module is part of the community.general collection (version 9.5.0).

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. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.gitlab_label.

New in community.general 8.3.0

Synopsis
Requirements
Parameters
Attributes
Examples
Return Values

Synopsis

When a label does not exist, it will be created.
When a label does exist, its value will be updated when the values are different.
Labels can be purged.

Requirements

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

python-gitlab python module
requests (Python library https://pypi.org/project/requests/)

Parameters

Parameter	Comments
api_job_token string added in community.general 4.2.0	GitLab CI job token for logging in.
api_oauth_token string added in community.general 4.2.0	GitLab OAuth token for logging in.
api_password string	The password to use for authentication against the API.
api_token string	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.
ca_path string added in community.general 8.1.0	The CA certificates bundle to use to verify GitLab server certificate.
group string	The path of the group. Either this or `project` is required.
labels list / elements=dictionary	A list of dictionaries that represents gitlab project’s or group’s labels. Default: `[]`
color string	The color of the label. Required when `state=present`.
description string	Label’s description.
name string / required	The name of the label.
new_name string	Optional field to change label’s name.
priority integer	Integer value to give priority to the label.
project string	The path and name of the project. Either this or `group` is required.
purge boolean	When set to `true`, delete all labels which are not mentioned in the task. Choices: `false` ← (default) `true`
state string	Create or delete project or group label. Choices: `"present"` ← (default) `"absent"`
validate_certs boolean	Whether or not to validate SSL certs when supplying a HTTPS endpoint. Choices: `false` `true` ← (default)

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in `check_mode` and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in `check_mode`), when in diff mode.

Examples

# same project's task can be executed for group
- name: Create one Label
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
        color: "#123456"
    state: present

- name: Create many group labels
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    group: "group1"
    labels:
      - name: label_one
        color: "#123456"
        description: this is a label
        priority: 20
      - name: label_two
        color: "#554422"
    state: present

- name: Create many project labels
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
        color: "#123456"
        description: this is a label
        priority: 20
      - name: label_two
        color: "#554422"
    state: present

- name: Set or update some labels
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
        color: "#224488"
    state: present

- name: Add label in check mode
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
        color: "#224488"
    check_mode: true

- name: Delete Label
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
    state: absent

- name: Change Label name
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    labels:
      - name: label_one
        new_name: label_two
    state: absent

- name: Purge all labels
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    purge: true

- name: Delete many labels
  community.general.gitlab_label:
    api_url: https://gitlab.com
    api_token: secret_access_token
    project: "group1/project1"
    state: absent
    labels:
      - name: label-abc123
      - name: label-two

Return Values

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

Key	Description
labels dictionary	Four lists of the labels which were added, updated, removed or exist. Returned: success
added list / elements=string	A list of labels which were created. Returned: always Sample: `["abcd", "label-one"]`
removed list / elements=string	A list of labels which were deleted. Returned: always Sample: `["defg", "new-label"]`
untouched list / elements=string	A list of labels which exist. Returned: always Sample: `["defg", "new-label"]`
updated list / elements=string	A list pre-existing labels whose values have been set. Returned: always Sample: `["defg", "new-label"]`
labels_obj dictionary	API object. Returned: success

Authors

Gabriele Pongelli (@gpongelli)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/gitlab_label_module.html