community.general.gitlab_label (8.5.0) — module

Install collection

Install with ansible-galaxy collection install community.general:==8.5.0

Add to requirements.yml

  collections:
    - name: community.general
      version: 8.5.0

Description

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

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

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Inputs

    
group:
    description:
    - The path of the group.  Either this or O(project) is required.
    required: false
    type: str

purge:
    default: false
    description:
    - When set to V(true), delete all labels which are not mentioned in the task.
    required: false
    type: bool

state:
    choices:
    - present
    - absent
    default: present
    description:
    - Create or delete project or group label.
    type: str

labels:
    default: []
    description:
    - A list of dictionaries that represents gitlab project's or group's labels.
    elements: dict
    required: false
    suboptions:
      color:
        description:
        - The color of the label.
        - Required when O(state=present).
        type: str
      description:
        default: null
        description:
        - Label's description.
        type: str
      name:
        description:
        - The name of the label.
        required: true
        type: str
      new_name:
        default: null
        description:
        - Optional field to change label's name.
        type: str
      priority:
        default: null
        description:
        - Integer value to give priority to the label.
        required: false
        type: int
    type: list

api_url:
    description:
    - The resolvable endpoint for the API.
    type: str

ca_path:
    description:
    - The CA certificates bundle to use to verify GitLab server certificate.
    type: str
    version_added: 8.1.0
    version_added_collection: community.general

project:
    description:
    - The path and name of the project.  Either this or O(group) is required.
    required: false
    type: str

api_token:
    description:
    - GitLab access token with API permissions.
    type: str

api_password:
    description:
    - The password to use for authentication against the API.
    type: str

api_username:
    description:
    - The username to use for authentication against the API.
    type: str

api_job_token:
    description:
    - GitLab CI job token for logging in.
    type: str
    version_added: 4.2.0
    version_added_collection: community.general

validate_certs:
    default: true
    description:
    - Whether or not to validate SSL certs when supplying a HTTPS endpoint.
    type: bool

api_oauth_token:
    description:
    - GitLab OAuth token for logging in.
    type: str
    version_added: 4.2.0
    version_added_collection: community.general

Outputs

labels:
  contains:
    added:
      description: A list of labels which were created.
      returned: always
      sample:
      - abcd
      - label-one
      type: list
    removed:
      description: A list of labels which were deleted.
      returned: always
      sample:
      - defg
      - new-label
      type: list
    untouched:
      description: A list of labels which exist.
      returned: always
      sample:
      - defg
      - new-label
      type: list
    updated:
      description: A list pre-existing labels whose values have been set.
      returned: always
      sample:
      - defg
      - new-label
      type: list
  description: Four lists of the labels which were added, updated, removed or exist.
  returned: success
  type: dict
labels_obj:
  description: API object.
  returned: success
  type: dict