diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml index dc7c990ea0..b02924d954 100644 --- a/.github/BOTMETA.yml +++ b/.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: diff --git a/plugins/modules/gitlab_issue.py b/plugins/modules/gitlab_issue.py new file mode 100644 index 0000000000..54ac1f1613 --- /dev/null +++ b/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() diff --git a/tests/integration/targets/gitlab_issue/aliases b/tests/integration/targets/gitlab_issue/aliases new file mode 100644 index 0000000000..4f4e3dcc93 --- /dev/null +++ b/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 diff --git a/tests/integration/targets/gitlab_issue/defaults/main.yml b/tests/integration/targets/gitlab_issue/defaults/main.yml new file mode 100644 index 0000000000..f94530fbf1 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/tests/integration/targets/gitlab_issue/files/description.md b/tests/integration/targets/gitlab_issue/files/description.md new file mode 100644 index 0000000000..f0ff12a77a --- /dev/null +++ b/tests/integration/targets/gitlab_issue/files/description.md @@ -0,0 +1,9 @@ + + +### Description + +Issue test description \ No newline at end of file diff --git a/tests/integration/targets/gitlab_issue/tasks/main.yml b/tests/integration/targets/gitlab_issue/tasks/main.yml new file mode 100644 index 0000000000..af1416c3dd --- /dev/null +++ b/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