2020-03-09 10:11:07 +01:00
|
|
|
#!/usr/bin/python
|
|
|
|
# -*- coding: utf-8 -*-
|
|
|
|
|
2022-08-05 12:28:29 +02:00
|
|
|
# Copyright (c) 2019, Guillaume Martinez (lunik@tiwabbit.fr)
|
|
|
|
# Copyright (c) 2015, Werner Dijkerman (ikben@werner-dijkerman.nl)
|
|
|
|
# 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
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
from __future__ import absolute_import, division, print_function
|
|
|
|
__metaclass__ = type
|
|
|
|
|
|
|
|
DOCUMENTATION = '''
|
|
|
|
---
|
|
|
|
module: gitlab_group
|
|
|
|
short_description: Creates/updates/deletes GitLab Groups
|
|
|
|
description:
|
|
|
|
- When the group does not exist in GitLab, it will be created.
|
|
|
|
- When the group does exist and state=absent, the group will be deleted.
|
|
|
|
author:
|
|
|
|
- Werner Dijkerman (@dj-wasabi)
|
|
|
|
- Guillaume Martinez (@Lunik)
|
|
|
|
requirements:
|
|
|
|
- python-gitlab python module
|
|
|
|
extends_documentation_fragment:
|
2021-12-20 21:59:12 +01:00
|
|
|
- community.general.auth_basic
|
|
|
|
- community.general.gitlab
|
2023-02-20 17:26:28 +01:00
|
|
|
- community.general.attributes
|
|
|
|
|
|
|
|
attributes:
|
|
|
|
check_mode:
|
|
|
|
support: full
|
|
|
|
diff_mode:
|
|
|
|
support: none
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
options:
|
|
|
|
name:
|
|
|
|
description:
|
|
|
|
- Name of the group you want to create.
|
|
|
|
required: true
|
|
|
|
type: str
|
|
|
|
path:
|
|
|
|
description:
|
|
|
|
- The path of the group you want to create, this will be api_url/group_path
|
|
|
|
- If not supplied, the group_name will be used.
|
|
|
|
type: str
|
|
|
|
description:
|
|
|
|
description:
|
|
|
|
- A description for the group.
|
|
|
|
type: str
|
|
|
|
state:
|
|
|
|
description:
|
|
|
|
- create or delete group.
|
|
|
|
- Possible values are present and absent.
|
|
|
|
default: present
|
|
|
|
type: str
|
|
|
|
choices: ["present", "absent"]
|
|
|
|
parent:
|
|
|
|
description:
|
|
|
|
- Allow to create subgroups
|
|
|
|
- Id or Full path of parent group in the form of group/name
|
|
|
|
type: str
|
|
|
|
visibility:
|
|
|
|
description:
|
|
|
|
- Default visibility of the group
|
|
|
|
choices: ["private", "internal", "public"]
|
|
|
|
default: private
|
|
|
|
type: str
|
2021-09-10 23:38:26 +02:00
|
|
|
project_creation_level:
|
|
|
|
description:
|
|
|
|
- Determine if developers can create projects in the group.
|
|
|
|
choices: ["developer", "maintainer", "noone"]
|
|
|
|
type: str
|
|
|
|
version_added: 3.7.0
|
|
|
|
auto_devops_enabled:
|
|
|
|
description:
|
|
|
|
- Default to Auto DevOps pipeline for all projects within this group.
|
|
|
|
type: bool
|
|
|
|
version_added: 3.7.0
|
|
|
|
subgroup_creation_level:
|
|
|
|
description:
|
|
|
|
- Allowed to create subgroups.
|
|
|
|
choices: ["maintainer", "owner"]
|
|
|
|
type: str
|
|
|
|
version_added: 3.7.0
|
2021-09-20 06:55:43 +02:00
|
|
|
require_two_factor_authentication:
|
|
|
|
description:
|
|
|
|
- Require all users in this group to setup two-factor authentication.
|
|
|
|
type: bool
|
|
|
|
version_added: 3.7.0
|
2021-11-30 06:12:28 +01:00
|
|
|
avatar_path:
|
|
|
|
description:
|
|
|
|
- Absolute path image to configure avatar. File size should not exceed 200 kb.
|
|
|
|
- This option is only used on creation, not for updates.
|
|
|
|
type: path
|
|
|
|
version_added: 4.2.0
|
2023-10-08 18:25:24 +02:00
|
|
|
force_delete:
|
|
|
|
description:
|
|
|
|
- Force delete group even if projects in it.
|
|
|
|
- Used only when O(state=absent).
|
|
|
|
type: bool
|
|
|
|
default: false
|
|
|
|
version_added: 7.5.0
|
2020-03-09 10:11:07 +01:00
|
|
|
'''
|
|
|
|
|
|
|
|
EXAMPLES = '''
|
|
|
|
- name: "Delete GitLab Group"
|
2020-07-13 21:50:31 +02:00
|
|
|
community.general.gitlab_group:
|
2020-03-09 10:11:07 +01:00
|
|
|
api_url: https://gitlab.example.com/
|
|
|
|
api_token: "{{ access_token }}"
|
2022-09-06 20:42:17 +02:00
|
|
|
validate_certs: false
|
2020-03-09 10:11:07 +01:00
|
|
|
name: my_first_group
|
|
|
|
state: absent
|
|
|
|
|
|
|
|
- name: "Create GitLab Group"
|
2020-07-13 21:50:31 +02:00
|
|
|
community.general.gitlab_group:
|
2020-03-09 10:11:07 +01:00
|
|
|
api_url: https://gitlab.example.com/
|
2022-09-06 20:42:17 +02:00
|
|
|
validate_certs: true
|
2020-03-09 10:11:07 +01:00
|
|
|
api_username: dj-wasabi
|
|
|
|
api_password: "MySecretPassword"
|
|
|
|
name: my_first_group
|
|
|
|
path: my_first_group
|
|
|
|
state: present
|
|
|
|
|
|
|
|
# The group will by created at https://gitlab.dj-wasabi.local/super_parent/parent/my_first_group
|
|
|
|
- name: "Create GitLab SubGroup"
|
2020-07-13 21:50:31 +02:00
|
|
|
community.general.gitlab_group:
|
2020-03-09 10:11:07 +01:00
|
|
|
api_url: https://gitlab.example.com/
|
2022-09-06 20:42:17 +02:00
|
|
|
validate_certs: true
|
2020-03-09 10:11:07 +01:00
|
|
|
api_username: dj-wasabi
|
|
|
|
api_password: "MySecretPassword"
|
|
|
|
name: my_first_group
|
|
|
|
path: my_first_group
|
|
|
|
state: present
|
|
|
|
parent: "super_parent/parent"
|
2021-09-10 23:38:26 +02:00
|
|
|
|
|
|
|
# Other group which only allows sub-groups - no projects
|
|
|
|
- name: "Create GitLab Group for SubGroups only"
|
|
|
|
community.general.gitlab_group:
|
|
|
|
api_url: https://gitlab.example.com/
|
2022-09-06 20:42:17 +02:00
|
|
|
validate_certs: true
|
2021-09-10 23:38:26 +02:00
|
|
|
api_username: dj-wasabi
|
|
|
|
api_password: "MySecretPassword"
|
|
|
|
name: my_main_group
|
|
|
|
path: my_main_group
|
|
|
|
state: present
|
|
|
|
project_creation_level: noone
|
|
|
|
auto_devops_enabled: false
|
|
|
|
subgroup_creation_level: maintainer
|
2020-03-09 10:11:07 +01:00
|
|
|
'''
|
|
|
|
|
|
|
|
RETURN = '''
|
|
|
|
msg:
|
|
|
|
description: Success or failure message
|
|
|
|
returned: always
|
|
|
|
type: str
|
|
|
|
sample: "Success"
|
|
|
|
|
|
|
|
result:
|
|
|
|
description: json parsed response from the server
|
|
|
|
returned: always
|
|
|
|
type: dict
|
|
|
|
|
|
|
|
error:
|
|
|
|
description: the error message returned by the GitLab API
|
|
|
|
returned: failed
|
|
|
|
type: str
|
|
|
|
sample: "400: path is already in use"
|
|
|
|
|
|
|
|
group:
|
|
|
|
description: API object
|
|
|
|
returned: always
|
|
|
|
type: dict
|
|
|
|
'''
|
|
|
|
|
|
|
|
from ansible.module_utils.api import basic_auth_argument_spec
|
2022-09-12 20:30:02 +02:00
|
|
|
from ansible.module_utils.basic import AnsibleModule
|
2021-06-26 23:59:11 +02:00
|
|
|
from ansible.module_utils.common.text.converters import to_native
|
2020-03-09 10:11:07 +01:00
|
|
|
|
2022-09-12 20:30:02 +02:00
|
|
|
from ansible_collections.community.general.plugins.module_utils.gitlab import (
|
2023-11-13 20:42:35 +01:00
|
|
|
auth_argument_spec, find_group, gitlab_authentication, gitlab
|
2022-09-12 20:30:02 +02:00
|
|
|
)
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
|
|
|
|
class GitLabGroup(object):
|
|
|
|
def __init__(self, module, gitlab_instance):
|
|
|
|
self._module = module
|
|
|
|
self._gitlab = gitlab_instance
|
2021-11-16 13:01:32 +01:00
|
|
|
self.group_object = None
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
'''
|
|
|
|
@param group Group object
|
|
|
|
'''
|
2021-11-16 13:01:32 +01:00
|
|
|
def get_group_id(self, group):
|
2020-03-09 10:11:07 +01:00
|
|
|
if group is not None:
|
|
|
|
return group.id
|
|
|
|
return None
|
|
|
|
|
|
|
|
'''
|
|
|
|
@param name Name of the group
|
|
|
|
@param parent Parent group full path
|
|
|
|
@param options Group options
|
|
|
|
'''
|
2021-11-16 13:01:32 +01:00
|
|
|
def create_or_update_group(self, name, parent, options):
|
2020-03-09 10:11:07 +01:00
|
|
|
changed = False
|
|
|
|
|
|
|
|
# Because we have already call userExists in main()
|
2021-11-16 13:01:32 +01:00
|
|
|
if self.group_object is None:
|
|
|
|
parent_id = self.get_group_id(parent)
|
2020-03-09 10:11:07 +01:00
|
|
|
|
2020-11-11 13:33:38 +01:00
|
|
|
payload = {
|
2020-03-09 10:11:07 +01:00
|
|
|
'name': name,
|
|
|
|
'path': options['path'],
|
|
|
|
'parent_id': parent_id,
|
2021-09-10 23:38:26 +02:00
|
|
|
'visibility': options['visibility'],
|
|
|
|
'project_creation_level': options['project_creation_level'],
|
|
|
|
'auto_devops_enabled': options['auto_devops_enabled'],
|
|
|
|
'subgroup_creation_level': options['subgroup_creation_level'],
|
2020-11-11 13:33:38 +01:00
|
|
|
}
|
|
|
|
if options.get('description'):
|
|
|
|
payload['description'] = options['description']
|
2021-09-27 21:50:21 +02:00
|
|
|
if options.get('require_two_factor_authentication'):
|
|
|
|
payload['require_two_factor_authentication'] = options['require_two_factor_authentication']
|
2021-11-16 13:01:32 +01:00
|
|
|
group = self.create_group(payload)
|
2021-11-30 06:12:28 +01:00
|
|
|
|
|
|
|
# add avatar to group
|
|
|
|
if options['avatar_path']:
|
|
|
|
try:
|
|
|
|
group.avatar = open(options['avatar_path'], 'rb')
|
|
|
|
except IOError as e:
|
|
|
|
self._module.fail_json(msg='Cannot open {0}: {1}'.format(options['avatar_path'], e))
|
2020-03-09 10:11:07 +01:00
|
|
|
changed = True
|
|
|
|
else:
|
2021-11-16 13:01:32 +01:00
|
|
|
changed, group = self.update_group(self.group_object, {
|
2020-03-09 10:11:07 +01:00
|
|
|
'name': name,
|
|
|
|
'description': options['description'],
|
2021-09-10 23:38:26 +02:00
|
|
|
'visibility': options['visibility'],
|
|
|
|
'project_creation_level': options['project_creation_level'],
|
|
|
|
'auto_devops_enabled': options['auto_devops_enabled'],
|
|
|
|
'subgroup_creation_level': options['subgroup_creation_level'],
|
2021-09-20 06:55:43 +02:00
|
|
|
'require_two_factor_authentication': options['require_two_factor_authentication'],
|
2021-09-10 23:38:26 +02:00
|
|
|
})
|
2020-03-09 10:11:07 +01:00
|
|
|
|
2021-11-16 13:01:32 +01:00
|
|
|
self.group_object = group
|
2020-03-09 10:11:07 +01:00
|
|
|
if changed:
|
|
|
|
if self._module.check_mode:
|
|
|
|
self._module.exit_json(changed=True, msg="Successfully created or updated the group %s" % name)
|
|
|
|
|
|
|
|
try:
|
|
|
|
group.save()
|
|
|
|
except Exception as e:
|
|
|
|
self._module.fail_json(msg="Failed to update group: %s " % e)
|
|
|
|
return True
|
|
|
|
else:
|
|
|
|
return False
|
|
|
|
|
|
|
|
'''
|
|
|
|
@param arguments Attributes of the group
|
|
|
|
'''
|
2021-11-16 13:01:32 +01:00
|
|
|
def create_group(self, arguments):
|
2020-03-09 10:11:07 +01:00
|
|
|
if self._module.check_mode:
|
|
|
|
return True
|
|
|
|
|
|
|
|
try:
|
2023-06-18 21:02:21 +02:00
|
|
|
# Filter out None values
|
|
|
|
filtered = dict((arg_key, arg_value) for arg_key, arg_value in arguments.items() if arg_value is not None)
|
|
|
|
|
|
|
|
group = self._gitlab.groups.create(filtered)
|
2020-03-09 10:11:07 +01:00
|
|
|
except (gitlab.exceptions.GitlabCreateError) as e:
|
|
|
|
self._module.fail_json(msg="Failed to create group: %s " % to_native(e))
|
|
|
|
|
|
|
|
return group
|
|
|
|
|
|
|
|
'''
|
|
|
|
@param group Group Object
|
|
|
|
@param arguments Attributes of the group
|
|
|
|
'''
|
2021-11-16 13:01:32 +01:00
|
|
|
def update_group(self, group, arguments):
|
2020-03-09 10:11:07 +01:00
|
|
|
changed = False
|
|
|
|
|
|
|
|
for arg_key, arg_value in arguments.items():
|
|
|
|
if arguments[arg_key] is not None:
|
|
|
|
if getattr(group, arg_key) != arguments[arg_key]:
|
|
|
|
setattr(group, arg_key, arguments[arg_key])
|
|
|
|
changed = True
|
|
|
|
|
|
|
|
return (changed, group)
|
|
|
|
|
2023-10-08 18:25:24 +02:00
|
|
|
'''
|
|
|
|
@param force To delete even if projects inside
|
|
|
|
'''
|
|
|
|
def delete_group(self, force=False):
|
2021-11-16 13:01:32 +01:00
|
|
|
group = self.group_object
|
2020-03-09 10:11:07 +01:00
|
|
|
|
2023-10-08 18:25:24 +02:00
|
|
|
if not force and len(group.projects.list(all=False)) >= 1:
|
2020-03-09 10:11:07 +01:00
|
|
|
self._module.fail_json(
|
2023-10-08 18:25:24 +02:00
|
|
|
msg=("There are still projects in this group. "
|
|
|
|
"These needs to be moved or deleted before this group can be removed. "
|
|
|
|
"Use 'force_delete' to 'true' to force deletion of existing projects.")
|
|
|
|
)
|
2020-03-09 10:11:07 +01:00
|
|
|
else:
|
|
|
|
if self._module.check_mode:
|
|
|
|
return True
|
|
|
|
|
|
|
|
try:
|
|
|
|
group.delete()
|
|
|
|
except Exception as e:
|
|
|
|
self._module.fail_json(msg="Failed to delete group: %s " % to_native(e))
|
|
|
|
|
|
|
|
'''
|
2023-10-08 18:25:24 +02:00
|
|
|
@param name Name of the group
|
2020-03-09 10:11:07 +01:00
|
|
|
@param full_path Complete path of the Group including parent group path. <parent_path>/<group_path>
|
|
|
|
'''
|
2021-11-16 13:01:32 +01:00
|
|
|
def exists_group(self, project_identifier):
|
|
|
|
# When group/user exists, object will be stored in self.group_object.
|
|
|
|
group = find_group(self._gitlab, project_identifier)
|
2020-03-09 10:11:07 +01:00
|
|
|
if group:
|
2021-11-16 13:01:32 +01:00
|
|
|
self.group_object = group
|
2020-03-09 10:11:07 +01:00
|
|
|
return True
|
|
|
|
return False
|
|
|
|
|
|
|
|
|
|
|
|
def main():
|
|
|
|
argument_spec = basic_auth_argument_spec()
|
2021-12-20 21:59:12 +01:00
|
|
|
argument_spec.update(auth_argument_spec())
|
2020-03-09 10:11:07 +01:00
|
|
|
argument_spec.update(dict(
|
|
|
|
name=dict(type='str', required=True),
|
|
|
|
path=dict(type='str'),
|
|
|
|
description=dict(type='str'),
|
|
|
|
state=dict(type='str', default="present", choices=["absent", "present"]),
|
|
|
|
parent=dict(type='str'),
|
|
|
|
visibility=dict(type='str', default="private", choices=["internal", "private", "public"]),
|
2021-09-10 23:38:26 +02:00
|
|
|
project_creation_level=dict(type='str', choices=['developer', 'maintainer', 'noone']),
|
|
|
|
auto_devops_enabled=dict(type='bool'),
|
|
|
|
subgroup_creation_level=dict(type='str', choices=['maintainer', 'owner']),
|
2021-09-20 06:55:43 +02:00
|
|
|
require_two_factor_authentication=dict(type='bool'),
|
2021-11-30 06:12:28 +01:00
|
|
|
avatar_path=dict(type='path'),
|
2023-10-08 18:25:24 +02:00
|
|
|
force_delete=dict(type='bool', default=False),
|
2020-03-09 10:11:07 +01:00
|
|
|
))
|
|
|
|
|
|
|
|
module = AnsibleModule(
|
|
|
|
argument_spec=argument_spec,
|
|
|
|
mutually_exclusive=[
|
|
|
|
['api_username', 'api_token'],
|
2021-12-20 21:59:12 +01:00
|
|
|
['api_username', 'api_oauth_token'],
|
|
|
|
['api_username', 'api_job_token'],
|
|
|
|
['api_token', 'api_oauth_token'],
|
|
|
|
['api_token', 'api_job_token'],
|
2020-03-09 10:11:07 +01:00
|
|
|
],
|
|
|
|
required_together=[
|
|
|
|
['api_username', 'api_password'],
|
|
|
|
],
|
|
|
|
required_one_of=[
|
2021-12-20 21:59:12 +01:00
|
|
|
['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
|
2020-03-09 10:11:07 +01:00
|
|
|
],
|
|
|
|
supports_check_mode=True,
|
|
|
|
)
|
2023-11-13 20:42:35 +01:00
|
|
|
|
|
|
|
# check prerequisites and connect to gitlab server
|
|
|
|
gitlab_instance = gitlab_authentication(module)
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
group_name = module.params['name']
|
|
|
|
group_path = module.params['path']
|
|
|
|
description = module.params['description']
|
|
|
|
state = module.params['state']
|
|
|
|
parent_identifier = module.params['parent']
|
|
|
|
group_visibility = module.params['visibility']
|
2021-09-10 23:38:26 +02:00
|
|
|
project_creation_level = module.params['project_creation_level']
|
|
|
|
auto_devops_enabled = module.params['auto_devops_enabled']
|
|
|
|
subgroup_creation_level = module.params['subgroup_creation_level']
|
2021-09-20 06:55:43 +02:00
|
|
|
require_two_factor_authentication = module.params['require_two_factor_authentication']
|
2021-11-30 06:12:28 +01:00
|
|
|
avatar_path = module.params['avatar_path']
|
2023-10-08 18:25:24 +02:00
|
|
|
force_delete = module.params['force_delete']
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
# Define default group_path based on group_name
|
|
|
|
if group_path is None:
|
|
|
|
group_path = group_name.replace(" ", "_")
|
|
|
|
|
|
|
|
gitlab_group = GitLabGroup(module, gitlab_instance)
|
|
|
|
|
|
|
|
parent_group = None
|
|
|
|
if parent_identifier:
|
2021-11-16 13:01:32 +01:00
|
|
|
parent_group = find_group(gitlab_instance, parent_identifier)
|
2020-03-09 10:11:07 +01:00
|
|
|
if not parent_group:
|
|
|
|
module.fail_json(msg="Failed create GitLab group: Parent group doesn't exists")
|
|
|
|
|
2021-11-16 13:01:32 +01:00
|
|
|
group_exists = gitlab_group.exists_group(parent_group.full_path + '/' + group_path)
|
2020-03-09 10:11:07 +01:00
|
|
|
else:
|
2021-11-16 13:01:32 +01:00
|
|
|
group_exists = gitlab_group.exists_group(group_path)
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
if state == 'absent':
|
|
|
|
if group_exists:
|
2023-10-08 18:25:24 +02:00
|
|
|
gitlab_group.delete_group(force=force_delete)
|
2020-03-09 10:11:07 +01:00
|
|
|
module.exit_json(changed=True, msg="Successfully deleted group %s" % group_name)
|
|
|
|
else:
|
|
|
|
module.exit_json(changed=False, msg="Group deleted or does not exists")
|
|
|
|
|
|
|
|
if state == 'present':
|
2021-11-16 13:01:32 +01:00
|
|
|
if gitlab_group.create_or_update_group(group_name, parent_group, {
|
|
|
|
"path": group_path,
|
|
|
|
"description": description,
|
|
|
|
"visibility": group_visibility,
|
|
|
|
"project_creation_level": project_creation_level,
|
|
|
|
"auto_devops_enabled": auto_devops_enabled,
|
|
|
|
"subgroup_creation_level": subgroup_creation_level,
|
|
|
|
"require_two_factor_authentication": require_two_factor_authentication,
|
2021-11-30 06:12:28 +01:00
|
|
|
"avatar_path": avatar_path,
|
2021-11-16 13:01:32 +01:00
|
|
|
}):
|
|
|
|
module.exit_json(changed=True, msg="Successfully created or updated the group %s" % group_name, group=gitlab_group.group_object._attrs)
|
2020-03-09 10:11:07 +01:00
|
|
|
else:
|
2021-11-16 13:01:32 +01:00
|
|
|
module.exit_json(changed=False, msg="No need to update the group %s" % group_name, group=gitlab_group.group_object._attrs)
|
2020-03-09 10:11:07 +01:00
|
|
|
|
|
|
|
|
|
|
|
if __name__ == '__main__':
|
|
|
|
main()
|