New module: gitlab_issue.py (#7539)

* feat(gitlab_issue): adds module for gitlab issues management

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* Apply suggestions from code review

Co-authored-by: Felix Fontein <felix@fontein.de>

* fix(gitlab_issue): assignee_ids and labels as lists

* docs(gitlab_issue): fix missing element types

* Apply suggestions from code review

Co-authored-by: Léo GATELLIER <26511053+lgatellier@users.noreply.github.com>

* chore(gitlab_issue): remove unnecessary parameter checks

* chore(gitlab_issue): renaming milestone_id parameter to milestone_search

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Léo GATELLIER <26511053+lgatellier@users.noreply.github.com>

.github/BOTMETA.yml

@@ -549,6 +549,8 @@ files:
     ignore: dj-wasabi
   $modules/gitlab_branch.py:
     maintainers: paytroff
+  $modules/gitlab_issue.py:
+    maintainers: zvaraondrej
   $modules/gitlab_merge_request.py:
     maintainers: zvaraondrej
   $modules/gitlab_project_variable.py:

plugins/modules/gitlab_issue.py

@@ -0,0 +1,408 @@
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright (c) 2023, Ondrej Zvara (ozvara1@gmail.com)
+# Based on code:
+# Copyright (c) 2021, Lennert Mertens (lennert@nubera.be)
+# Copyright (c) 2021, Werner Dijkerman (ikben@werner-dijkerman.nl)
+# Copyright (c) 2015, Werner Dijkerman (ikben@werner-dijkerman.nl)
+# Copyright (c) 2019, Guillaume Martinez (lunik@tiwabbit.fr)
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+DOCUMENTATION = '''
+module: gitlab_issue
+short_description: Create, update, or delete GitLab issues
+version_added: '8.1.0'
+description:
+  - Creates an issue if it does not exist.
+  - When an issue does exist, it will be updated if the provided parameters are different.
+  - When an issue does exist and O(state=absent), the issue will be deleted.
+  - When multiple issues are detected, the task fails.
+  - Existing issues are matched based on O(title) and O(state_filter) filters.
+author:
+  - zvaraondrej (@zvaraondrej)
+requirements:
+  - python-gitlab >= 2.3.0
+extends_documentation_fragment:
+  - community.general.auth_basic
+  - community.general.gitlab
+  - community.general.attributes
+
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: none
+
+options:
+  assignee_ids:
+    description:
+      - A list of assignee usernames omitting V(@) character.
+      - Set to an empty array to unassign all assignees.
+    type: list
+    elements: str
+  description:
+    description:
+      - A description of the issue.
+      - Gets overridden by a content of file specified at O(description_path), if found.
+    type: str
+  description_path:
+    description:
+      - A path of file containing issue's description.
+      - Accepts MarkDown formatted files.
+    type: path
+  issue_type:
+    description:
+      - Type of the issue.
+    default: issue
+    type: str
+    choices: ["issue", "incident", "test_case"]
+  labels:
+    description:
+      - A list of label names.
+      - Set to an empty array to remove all labels.
+    type: list
+    elements: str
+  milestone_search:
+    description:
+      - The name of the milestone.
+      - Set to empty string to unassign milestone.
+    type: str
+  milestone_group_id:
+    description:
+      - The path or numeric ID of the group hosting desired milestone.
+    type: str
+  project:
+    description:
+      - The path or name of the project.
+    required: true
+    type: str
+  state:
+    description:
+      - Create or delete issue.
+    default: present
+    type: str
+    choices: ["present", "absent"]
+  state_filter:
+    description:
+      - Filter specifying state of issues while searching.
+    type: str
+    choices: ["opened", "closed"]
+    default: opened
+  title:
+    description:
+      - A title for the issue. The title is used as a unique identifier to ensure idempotency.
+    type: str
+    required: true
+'''
+
+
+EXAMPLES = '''
+- name: Create Issue
+  community.general.gitlab_issue:
+    api_url: https://gitlab.com
+    api_token: secret_access_token
+    project: "group1/project1"
+    title: "Ansible demo Issue"
+    description: "Demo Issue description"
+    labels:
+        - Ansible
+        - Demo
+    assignee_ids:
+        - testassignee
+    state_filter: "opened"
+    state: present
+
+- name: Delete Issue
+  community.general.gitlab_issue:
+    api_url: https://gitlab.com
+    api_token: secret_access_token
+    project: "group1/project1"
+    title: "Ansible demo Issue"
+    state_filter: "opened"
+    state: absent
+'''
+
+RETURN = r'''
+msg:
+  description: Success or failure message.
+  returned: always
+  type: str
+  sample: "Success"
+
+issue:
+  description: API object.
+  returned: success
+  type: dict
+'''
+
+from ansible.module_utils.basic import AnsibleModule
+from ansible.module_utils.api import basic_auth_argument_spec
+from ansible.module_utils.common.text.converters import to_native, to_text
+
+from ansible_collections.community.general.plugins.module_utils.version import LooseVersion
+from ansible_collections.community.general.plugins.module_utils.gitlab import (
+    auth_argument_spec, gitlab_authentication, gitlab, find_project, find_group
+)
+
+
+class GitlabIssue(object):
+
+    def __init__(self, module, project, gitlab_instance):
+        self._gitlab = gitlab_instance
+        self._module = module
+        self.project = project
+
+    '''
+    @param milestone_id Title of the milestone
+    '''
+    def get_milestone(self, milestone_id, group):
+        milestones = []
+        try:
+            milestones = group.milestones.list(search=milestone_id)
+        except gitlab.exceptions.GitlabGetError as e:
+            self._module.fail_json(msg="Failed to list the Milestones: %s" % to_native(e))
+
+        if len(milestones) > 1:
+            self._module.fail_json(msg="Multiple Milestones matched search criteria.")
+        if len(milestones) < 1:
+            self._module.fail_json(msg="No Milestones matched search criteria.")
+        if len(milestones) == 1:
+            try:
+                return group.milestones.get(id=milestones[0].id)
+            except gitlab.exceptions.GitlabGetError as e:
+                self._module.fail_json(msg="Failed to get the Milestones: %s" % to_native(e))
+
+    '''
+    @param title Title of the Issue
+    @param state_filter Issue's state to filter on
+    '''
+    def get_issue(self, title, state_filter):
+        issues = []
+        try:
+            issues = self.project.issues.list(title=title, state=state_filter)
+        except gitlab.exceptions.GitlabGetError as e:
+            self._module.fail_json(msg="Failed to list the Issues: %s" % to_native(e))
+
+        if len(issues) > 1:
+            self._module.fail_json(msg="Multiple Issues matched search criteria.")
+        if len(issues) == 1:
+            try:
+                return self.project.issues.get(id=issues[0].iid)
+            except gitlab.exceptions.GitlabGetError as e:
+                self._module.fail_json(msg="Failed to get the Issue: %s" % to_native(e))
+
+    '''
+    @param username Name of the user
+    '''
+    def get_user(self, username):
+        users = []
+        try:
+            users = [user for user in self.project.users.list(username=username, all=True) if user.username == username]
+        except gitlab.exceptions.GitlabGetError as e:
+            self._module.fail_json(msg="Failed to list the users: %s" % to_native(e))
+
+        if len(users) > 1:
+            self._module.fail_json(msg="Multiple Users matched search criteria.")
+        elif len(users) < 1:
+            self._module.fail_json(msg="No User matched search criteria.")
+        else:
+            return users[0]
+
+    '''
+    @param users List of usernames
+    '''
+    def get_user_ids(self, users):
+        return [self.get_user(user).id for user in users]
+
+    '''
+    @param options Options of the Issue
+    '''
+    def create_issue(self, options):
+        if self._module.check_mode:
+            self._module.exit_json(changed=True, msg="Successfully created Issue '%s'." % options["title"])
+
+        try:
+            return self.project.issues.create(options)
+        except gitlab.exceptions.GitlabCreateError as e:
+            self._module.fail_json(msg="Failed to create Issue: %s " % to_native(e))
+
+    '''
+    @param issue Issue object to delete
+    '''
+    def delete_issue(self, issue):
+        if self._module.check_mode:
+            self._module.exit_json(changed=True, msg="Successfully deleted Issue '%s'." % issue["title"])
+
+        try:
+            return issue.delete()
+        except gitlab.exceptions.GitlabDeleteError as e:
+            self._module.fail_json(msg="Failed to delete Issue: '%s'." % to_native(e))
+
+    '''
+    @param issue Issue object to update
+    @param options Options of the Issue
+    '''
+    def update_issue(self, issue, options):
+        if self._module.check_mode:
+            self._module.exit_json(changed=True, msg="Successfully updated Issue '%s'." % issue["title"])
+
+        try:
+            return self.project.issues.update(issue.iid, options)
+        except gitlab.exceptions.GitlabUpdateError as e:
+            self._module.fail_json(msg="Failed to update Issue %s." % to_native(e))
+
+    '''
+    @param issue Issue object to evaluate
+    @param options New options to update Issue with
+    '''
+    def issue_has_changed(self, issue, options):
+        for key, value in options.items():
+            if value is not None:
+
+                if key == 'milestone_id':
+                    old_milestone = getattr(issue, 'milestone')['id'] if getattr(issue, 'milestone') else ""
+                    if options[key] != old_milestone:
+                        return True
+                elif key == 'assignee_ids':
+                    if options[key] != sorted([user["id"] for user in getattr(issue, 'assignees')]):
+                        return True
+
+                elif key == 'labels':
+                    if options[key] != sorted(getattr(issue, key)):
+                        return True
+
+                elif getattr(issue, key) != value:
+                    return True
+
+        return False
+
+
+def main():
+    argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
+    argument_spec.update(
+        assignee_ids=dict(type='list', elements='str', required=False),
+        description=dict(type='str', required=False),
+        description_path=dict(type='path', required=False),
+        issue_type=dict(type='str', default='issue', choices=["issue", "incident", "test_case"], required=False),
+        labels=dict(type='list', elements='str', required=False),
+        milestone_search=dict(type='str', required=False),
+        milestone_group_id=dict(type='str', required=False),
+        project=dict(type='str', required=True),
+        state=dict(type='str', default="present", choices=["absent", "present"]),
+        state_filter=dict(type='str', default="opened", choices=["opened", "closed"]),
+        title=dict(type='str', required=True),
+    )
+
+    module = AnsibleModule(
+        argument_spec=argument_spec,
+        mutually_exclusive=[
+            ['api_username', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
+            ['description', 'description_path'],
+        ],
+        required_together=[
+            ['api_username', 'api_password'],
+            ['milestone_search', 'milestone_group_id'],
+        ],
+        required_one_of=[
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
+        ],
+        supports_check_mode=True
+    )
+
+    assignee_ids = module.params['assignee_ids']
+    description = module.params['description']
+    description_path = module.params['description_path']
+    issue_type = module.params['issue_type']
+    labels = module.params['labels']
+    milestone_id = module.params['milestone_search']
+    milestone_group_id = module.params['milestone_group_id']
+    project = module.params['project']
+    state = module.params['state']
+    state_filter = module.params['state_filter']
+    title = module.params['title']
+
+    gitlab_version = gitlab.__version__
+    if LooseVersion(gitlab_version) < LooseVersion('2.3.0'):
+        module.fail_json(msg="community.general.gitlab_issue requires python-gitlab Python module >= 2.3.0 (installed version: [%s])."
+                             " Please upgrade python-gitlab to version 2.3.0 or above." % gitlab_version)
+
+    # check prerequisites and connect to gitlab server
+    gitlab_instance = gitlab_authentication(module)
+
+    this_project = find_project(gitlab_instance, project)
+    if this_project is None:
+        module.fail_json(msg="Failed to get the project: %s" % project)
+
+    this_gitlab = GitlabIssue(module=module, project=this_project, gitlab_instance=gitlab_instance)
+
+    if milestone_id and milestone_group_id:
+        this_group = find_group(gitlab_instance, milestone_group_id)
+        if this_group is None:
+            module.fail_json(msg="Failed to get the group: %s" % milestone_group_id)
+
+        milestone_id = this_gitlab.get_milestone(milestone_id, this_group).id
+
+    this_issue = this_gitlab.get_issue(title, state_filter)
+
+    if state == "present":
+        if description_path:
+            try:
+                with open(description_path, 'rb') as f:
+                    description = to_text(f.read(), errors='surrogate_or_strict')
+            except IOError as e:
+                module.fail_json(msg='Cannot open {0}: {1}'.format(description_path, e))
+
+        # sorting necessary in order to properly detect changes, as we don't want to get false positive
+        # results due to differences in ids ordering;
+        assignee_ids = sorted(this_gitlab.get_user_ids(assignee_ids)) if assignee_ids else assignee_ids
+        labels = sorted(labels) if labels else labels
+
+        options = {
+            "title": title,
+            "description": description,
+            "labels": labels,
+            "issue_type": issue_type,
+            "milestone_id": milestone_id,
+            "assignee_ids": assignee_ids,
+        }
+
+        if not this_issue:
+            issue = this_gitlab.create_issue(options)
+            module.exit_json(
+                changed=True, msg="Created Issue '{t}'.".format(t=title),
+                issue=issue.asdict()
+            )
+        else:
+            if this_gitlab.issue_has_changed(this_issue, options):
+                issue = this_gitlab.update_issue(this_issue, options)
+                module.exit_json(
+                    changed=True, msg="Updated Issue '{t}'.".format(t=title),
+                    issue=issue
+                )
+            else:
+                module.exit_json(
+                    changed=False, msg="Issue '{t}' already exists".format(t=title),
+                    issue=this_issue.asdict()
+                )
+    elif state == "absent":
+        if not this_issue:
+            module.exit_json(changed=False, msg="Issue '{t}' does not exist or has already been deleted.".format(t=title))
+        else:
+            issue = this_gitlab.delete_issue(this_issue)
+            module.exit_json(
+                changed=True, msg="Issue '{t}' deleted.".format(t=title),
+                issue=issue
+            )
+
+
+if __name__ == '__main__':
+    main()

tests/integration/targets/gitlab_issue/aliases

@@ -0,0 +1,6 @@
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+gitlab/ci
+disabled

tests/integration/targets/gitlab_issue/defaults/main.yml

@@ -0,0 +1,15 @@
+---
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+gitlab_branch: ansible_test_branch
+gitlab_project_name: ansible_test_project
+gitlab_project_group: ansible_test_group
+gitlab_host: ansible_test_host
+gitlab_api_token: ansible_test_api_token
+gitlab_labels: ansible_test_label
+gitlab_milestone_search: ansible_test_milestone_search
+gitlab_milestone_group_id: ansible_test_milestone_group_id
+gitlab_assignee_ids: ansible_test_assignee_ids
+gitlab_description_path: ansible_test_description_path

tests/integration/targets/gitlab_issue/files/description.md

@@ -0,0 +1,9 @@
+<!--
+Copyright (c) Ansible Project
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+### Description
+
+Issue test description

tests/integration/targets/gitlab_issue/tasks/main.yml

@@ -0,0 +1,150 @@
+---
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+- name: Install required libs
+  pip:
+    name: python-gitlab
+    state: present
+
+- block:
+  - name: Create {{ gitlab_project_name }} project
+    gitlab_project:
+      api_url: "{{ gitlab_host }}"
+      validate_certs: true
+      api_token: "{{ gitlab_api_token }}"
+      name: "{{ gitlab_project_name }}"
+      group: "{{ gitlab_project_group }}"
+      default_branch: "{{ gitlab_branch }}"
+      initialize_with_readme: true
+      state: present
+
+  - name: Create Issue
+    gitlab_issue:
+      api_token: "{{ gitlab_api_token }}"
+      api_url: "{{ gitlab_host }}"
+      description: "Test description"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      state: present
+      title: "Ansible test issue"
+    register: gitlab_issue_create
+
+  - name: Test Issue Created
+    assert:
+      that:
+        - gitlab_issue_create is changed
+
+  - name: Create Issue ( Idempotency test )
+    gitlab_issue:
+      api_token: "{{ gitlab_api_token }}"
+      api_url: "{{ gitlab_host }}"
+      description: "Test description"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      state: present
+      title: "Ansible test issue"
+    register: gitlab_issue_create_idempotence
+
+  - name: Test Create Issue is Idempotent
+    assert:
+      that:
+        - gitlab_issue_create_idempotence is not changed
+
+  - name: Update Issue Test ( Additions )
+    gitlab_issue:
+      api_token: "{{ gitlab_api_token }}"
+      api_url: "{{ gitlab_host }}"
+      assignee_ids: "{{ gitlab_assignee_ids }}"
+      description_path: "{{ gitlab_description_path }}"
+      labels: "{{ gitlab_labels }}"
+      milestone_search: "{{ gitlab_milestone_search }}"
+      milestone_group_id: "{{ gitlab_milestone_group_id }}"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      state: present
+      title: "Ansible test issue"
+    register: gitlab_issue_update_additions
+
+  - name: Test Issue Updated ( Additions )
+    assert:
+      that:
+        - gitlab_issue_update_additions.issue.labels[0] == "{{ gitlab_labels[0] }}"
+        - gitlab_issue_update_additions.issue.assignees[0].username == "{{ gitlab_assignee_ids[0] }}"
+        - "'### Description\n\nIssue test description' in gitlab_issue_update_additions.issue.description"
+        - gitlab_issue_update_additions.issue.milestone.title == "{{ gitlab_milestone_search }}"
+
+  - name: Update Issue Test ( Persistence )
+    gitlab_issue:
+      api_token: "{{ gitlab_api_token }}"
+      api_url: "{{ gitlab_host }}"
+      description_path: "{{ gitlab_description_path }}"
+      milestone_search: "{{ gitlab_milestone_search }}"
+      milestone_group_id: "{{ gitlab_milestone_group_id }}"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      state: present
+      title: "Ansible test issue"
+    register: gitlab_issue_update_persistence
+
+  - name: Test issue Not Updated ( Persistence )
+    assert:
+      that:
+        - gitlab_issue_update_persistence.issue.labels[0] == "{{ gitlab_labels[0] }}"
+        - gitlab_issue_update_persistence.issue.assignees[0].username == "{{ gitlab_assignee_ids[0] }}"
+
+  - name: Update Issue Test ( Removals )
+    gitlab_issue:
+      api_token: "{{ gitlab_api_token }}"
+      api_url: "{{ gitlab_host }}"
+      assignee_ids: []
+      description_path: "{{ gitlab_description_path }}"
+      labels: []
+      milestone_search: ""
+      milestone_group_id: ""
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      state: present
+      title: "Ansible test issue"
+    register: gitlab_issue_update_removal
+
+  - name: Test issue updated
+    assert:
+      that:
+        - gitlab_issue_update_removal.issue.labels == []
+        - gitlab_issue_update_removal.issue.assignees == []
+        - gitlab_issue_update_removal.issue.milestone == None
+
+  - name: Delete Issue
+    gitlab_issue:
+      api_url: "{{ gitlab_host }}"
+      api_token: "{{ gitlab_api_token }}"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      title: "Ansible test issue"
+      state: absent
+    register: gitlab_issue_delete
+
+  - name: Test issue is deleted
+    assert:
+      that:
+        - gitlab_issue_delete is changed
+
+  always:
+  - name: Delete Issue
+    gitlab_issue:
+      api_url: "{{ gitlab_host }}"
+      api_token: "{{ gitlab_api_token }}"
+      project: "{{ gitlab_project_group }}/{{ gitlab_project_name }}"
+      title: "Ansible test issue"
+      state_filter: "opened"
+      state: absent
+    register: gitlab_issue_delete
+  - name: Clean up {{ gitlab_project_name }}
+    gitlab_project:
+      api_url: "{{ gitlab_host }}"
+      validate_certs: false
+      api_token: "{{ gitlab_api_token }}"
+      name: "{{ gitlab_project_name }}"
+      group: "{{ gitlab_project_group }}"
+      state: absent