diff --git a/changelogs/fragments/3319-gitlab_project_members_enhancement.yml b/changelogs/fragments/3319-gitlab_project_members_enhancement.yml new file mode 100644 index 0000000000..7795cd1f02 --- /dev/null +++ b/changelogs/fragments/3319-gitlab_project_members_enhancement.yml @@ -0,0 +1,3 @@ +minor_changes: + - gitlab_project_members - ``gitlab_user`` can now also be a list of users (https://github.com/ansible-collections/community.general/pull/3319). + - gitlab_project_members - added functionality to set all members exactly as given (https://github.com/ansible-collections/community.general/pull/3319). diff --git a/plugins/modules/source_control/gitlab/gitlab_project_members.py b/plugins/modules/source_control/gitlab/gitlab_project_members.py index 0ae8f4b25c..51f60d459f 100644 --- a/plugins/modules/source_control/gitlab/gitlab_project_members.py +++ b/plugins/modules/source_control/gitlab/gitlab_project_members.py @@ -53,15 +53,37 @@ options: type: str gitlab_user: description: - - The username of the member to add to/remove from the GitLab project. - required: true - type: str + - A username or a list of usernames to add to/remove from the GitLab project. + - Mutually exclusive with I(gitlab_users_access). + type: list + elements: str access_level: description: - The access level for the user. - Required if I(state=present), user state is set to present. type: str choices: ['guest', 'reporter', 'developer', 'maintainer'] + gitlab_users_access: + description: + - Provide a list of user to access level mappings. + - Every dictionary in this list specifies a user (by username) and the access level the user should have. + - Mutually exclusive with I(gitlab_user) and I(access_level). + - Use together with I(purge_users) to remove all users not specified here from the project. + type: list + elements: dict + suboptions: + name: + description: A username or a list of usernames to add to/remove from the GitLab project. + type: str + required: true + access_level: + description: + - The access level for the user. + - Required if I(state=present), user state is set to present. + type: str + choices: ['guest', 'reporter', 'developer', 'maintainer'] + required: true + version_added: 3.7.0 state: description: - State of the member in the project. @@ -70,6 +92,15 @@ options: choices: ['present', 'absent'] default: 'present' type: str + purge_users: + description: + - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list. + If omitted do not purge orphaned members. + - Is only used when I(state=present). + type: list + elements: str + choices: ['guest', 'reporter', 'developer', 'maintainer'] + version_added: 3.7.0 notes: - Supports C(check_mode). ''' @@ -93,6 +124,51 @@ EXAMPLES = r''' project: projectname gitlab_user: username state: absent + +- name: Add a list of Users to A GitLab project + community.general.gitlab_project_members: + api_url: 'https://gitlab.example.com' + api_token: 'Your-Private-Token' + gitlab_project: projectname + gitlab_user: + - user1 + - user2 + access_level: developer + state: present + +- name: Add a list of Users with Dedicated Access Levels to A GitLab project + community.general.gitlab_project_members: + api_url: 'https://gitlab.example.com' + api_token: 'Your-Private-Token' + project: projectname + gitlab_users_access: + - name: user1 + access_level: developer + - name: user2 + access_level: maintainer + state: present + +- name: Add a user, remove all others which might be on this access level + community.general.gitlab_project_members: + api_url: 'https://gitlab.example.com' + api_token: 'Your-Private-Token' + project: projectname + gitlab_user: username + access_level: developer + pruge_users: developer + state: present + +- name: Remove a list of Users with Dedicated Access Levels to A GitLab project + community.general.gitlab_project_members: + api_url: 'https://gitlab.example.com' + api_token: 'Your-Private-Token' + project: projectname + gitlab_users_access: + - name: user1 + access_level: developer + - name: user2 + access_level: maintainer + state: absent ''' RETURN = r''' # ''' @@ -132,6 +208,17 @@ class GitLabProjectMembers(object): project = self._gitlab.projects.get(gitlab_project_id) return project.members.list(all=True) + # get single member in a project by user name + def get_member_in_a_project(self, gitlab_project_id, gitlab_user_id): + member = None + project = self._gitlab.projects.get(gitlab_project_id) + try: + member = project.members.get(gitlab_user_id) + if member: + return member + except gitlab.exceptions.GitlabGetError as e: + return None + # check if the user is a member of the project def is_user_a_member(self, members, gitlab_user_id): for member in members: @@ -141,27 +228,14 @@ class GitLabProjectMembers(object): # add user to a project def add_member_to_project(self, gitlab_user_id, gitlab_project_id, access_level): - try: - project = self._gitlab.projects.get(gitlab_project_id) - add_member = project.members.create( - {'user_id': gitlab_user_id, 'access_level': access_level}) - - if add_member: - return add_member.username - - except (gitlab.exceptions.GitlabCreateError) as e: - self._module.fail_json( - msg="Failed to add member to the project, project ID %s: %s" % (gitlab_project_id, e)) + project = self._gitlab.projects.get(gitlab_project_id) + add_member = project.members.create( + {'user_id': gitlab_user_id, 'access_level': access_level}) # remove user from a project def remove_user_from_project(self, gitlab_user_id, gitlab_project_id): - try: - project = self._gitlab.projects.get(gitlab_project_id) - project.members.delete(gitlab_user_id) - - except (gitlab.exceptions.GitlabDeleteError) as e: - self._module.fail_json( - msg="Failed to remove member from GitLab project, ID %s: %s" % (gitlab_project_id, e)) + project = self._gitlab.projects.get(gitlab_project_id) + project.members.delete(gitlab_user_id) # get user's access level def get_user_access_level(self, members, gitlab_user_id): @@ -173,12 +247,8 @@ class GitLabProjectMembers(object): def update_user_access_level(self, members, gitlab_user_id, access_level): for member in members: if member.id == gitlab_user_id: - try: - member.access_level = access_level - member.save() - except (gitlab.exceptions.GitlabCreateError) as e: - self._module.fail_json( - msg="Failed to update the access level for the member, %s: %s" % (gitlab_user_id, e)) + member.access_level = access_level + member.save() def main(): @@ -186,9 +256,20 @@ def main(): argument_spec.update(dict( api_token=dict(type='str', required=True, no_log=True), project=dict(type='str', required=True), - gitlab_user=dict(type='str', required=True), + gitlab_user=dict(type='list', elements='str'), state=dict(type='str', default='present', choices=['present', 'absent']), - access_level=dict(type='str', required=False, choices=['guest', 'reporter', 'developer', 'maintainer']) + access_level=dict(type='str', choices=['guest', 'reporter', 'developer', 'maintainer']), + purge_users=dict(type='list', elements='str', choices=[ + 'guest', 'reporter', 'developer', 'maintainer']), + gitlab_users_access=dict( + type='list', + elements='dict', + options=dict( + name=dict(type='str', required=True), + access_level=dict(type='str', choices=[ + 'guest', 'reporter', 'developer', 'maintainer'], required=True), + ) + ), )) module = AnsibleModule( @@ -196,15 +277,19 @@ def main(): mutually_exclusive=[ ['api_username', 'api_token'], ['api_password', 'api_token'], + ['gitlab_user', 'gitlab_users_access'], + ['access_level', 'gitlab_users_access'], ], required_together=[ ['api_username', 'api_password'], + ['gitlab_user', 'access_level'], ], required_one_of=[ ['api_username', 'api_token'], + ['gitlab_user', 'gitlab_users_access'], ], required_if=[ - ['state', 'present', ['access_level']], + ['state', 'present', ['access_level', 'gitlab_users_access'], True], ], supports_check_mode=True, ) @@ -212,71 +297,168 @@ def main(): if not HAS_PY_GITLAB: module.fail_json(msg=missing_required_lib('python-gitlab', url='https://python-gitlab.readthedocs.io/en/stable/'), exception=GITLAB_IMP_ERR) + access_level_int = { + 'guest': gitlab.GUEST_ACCESS, + 'reporter': gitlab.REPORTER_ACCESS, + 'developer': gitlab.DEVELOPER_ACCESS, + 'maintainer': gitlab.MAINTAINER_ACCESS, + } + gitlab_project = module.params['project'] - gitlab_user = module.params['gitlab_user'] state = module.params['state'] access_level = module.params['access_level'] + purge_users = module.params['purge_users'] - # convert access level string input to int - if access_level: - access_level_int = { - 'guest': gitlab.GUEST_ACCESS, - 'reporter': gitlab.REPORTER_ACCESS, - 'developer': gitlab.DEVELOPER_ACCESS, - 'maintainer': gitlab.MAINTAINER_ACCESS - } - - access_level = access_level_int[access_level] + if purge_users: + purge_users = [access_level_int[level] for level in purge_users] # connect to gitlab server gl = gitlabAuthentication(module) project = GitLabProjectMembers(module, gl) - gitlab_user_id = project.get_user_id(gitlab_user) gitlab_project_id = project.get_project(gitlab_project) # project doesn't exist if not gitlab_project_id: module.fail_json(msg="project '%s' not found." % gitlab_project) - # user doesn't exist - if not gitlab_user_id: - if state == 'absent': - module.exit_json(changed=False, result="user '%s' not found, and thus also not part of the project" % gitlab_user) - else: - module.fail_json(msg="user '%s' not found." % gitlab_user) + members = [] + if module.params['gitlab_user'] is not None: + gitlab_users_access = [] + gitlab_users = module.params['gitlab_user'] + for gl_user in gitlab_users: + gitlab_users_access.append( + {'name': gl_user, 'access_level': access_level_int[access_level] if access_level else None}) + elif module.params['gitlab_users_access'] is not None: + gitlab_users_access = module.params['gitlab_users_access'] + for user_level in gitlab_users_access: + user_level['access_level'] = access_level_int[user_level['access_level']] - members = project.get_members_in_a_project(gitlab_project_id) - is_user_a_member = project.is_user_a_member(members, gitlab_user_id) - - # check if the user is a member in the project - if not is_user_a_member: - if state == 'present': - # add user to the project - if not module.check_mode: - project.add_member_to_project(gitlab_user_id, gitlab_project_id, access_level) - module.exit_json(changed=True, result="Successfully added user '%s' to the project." % gitlab_user) - # state as absent - else: - module.exit_json(changed=False, result="User, '%s', is not a member in the project. No change to report" % gitlab_user) - # in case that a user is a member + if len(gitlab_users_access) == 1 and not purge_users: + # only single user given + members = [project.get_member_in_a_project( + gitlab_project_id, project.get_user_id(gitlab_users_access[0]['name']))] + if members[0] is None: + members = [] + elif len(gitlab_users_access) > 1 or purge_users: + # list of users given + members = project.get_members_in_a_project(gitlab_project_id) else: - if state == 'present': - # compare the access level - user_access_level = project.get_user_access_level(members, gitlab_user_id) - if user_access_level == access_level: - module.exit_json(changed=False, result="User, '%s', is already a member in the project. No change to report" % gitlab_user) + module.exit_json(changed='OK', result="Nothing to do, please give at least one user or set purge_users true.", + result_data=[]) + + changed = False + error = False + changed_users = [] + changed_data = [] + + for gitlab_user in gitlab_users_access: + gitlab_user_id = project.get_user_id(gitlab_user['name']) + + # user doesn't exist + if not gitlab_user_id: + if state == 'absent': + changed_users.append("user '%s' not found, and thus also not part of the project" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'OK', + 'msg': "user '%s' not found, and thus also not part of the project" % gitlab_user['name']}) else: - # update the access level for the user - if not module.check_mode: - project.update_user_access_level(members, gitlab_user_id, access_level) - module.exit_json(changed=True, result="Successfully updated the access level for the user, '%s'" % gitlab_user) + error = True + changed_users.append("user '%s' not found." % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED', + 'msg': "user '%s' not found." % gitlab_user['name']}) + continue + + is_user_a_member = project.is_user_a_member(members, gitlab_user_id) + + # check if the user is a member in the project + if not is_user_a_member: + if state == 'present': + # add user to the project + try: + if not module.check_mode: + project.add_member_to_project(gitlab_user_id, gitlab_project_id, gitlab_user['access_level']) + changed = True + changed_users.append("Successfully added user '%s' to project" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'CHANGED', + 'msg': "Successfully added user '%s' to project" % gitlab_user['name']}) + except (gitlab.exceptions.GitlabCreateError) as e: + error = True + changed_users.append("Failed to updated the access level for the user, '%s'" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED', + 'msg': "Not allowed to add the access level for the member, %s: %s" % (gitlab_user['name'], e)}) + # state as absent + else: + changed_users.append("User, '%s', is not a member in the project. No change to report" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'OK', + 'msg': "User, '%s', is not a member in the project. No change to report" % gitlab_user['name']}) + # in case that a user is a member else: - # remove the user from the project - if not module.check_mode: - project.remove_user_from_project(gitlab_user_id, gitlab_project_id) - module.exit_json(changed=True, result="Successfully removed user, '%s', from the project" % gitlab_user) + if state == 'present': + # compare the access level + user_access_level = project.get_user_access_level(members, gitlab_user_id) + if user_access_level == gitlab_user['access_level']: + changed_users.append("User, '%s', is already a member in the project. No change to report" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'OK', + 'msg': "User, '%s', is already a member in the project. No change to report" % gitlab_user['name']}) + else: + # update the access level for the user + try: + if not module.check_mode: + project.update_user_access_level(members, gitlab_user_id, gitlab_user['access_level']) + changed = True + changed_users.append("Successfully updated the access level for the user, '%s'" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'CHANGED', + 'msg': "Successfully updated the access level for the user, '%s'" % gitlab_user['name']}) + except (gitlab.exceptions.GitlabUpdateError) as e: + error = True + changed_users.append("Failed to updated the access level for the user, '%s'" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED', + 'msg': "Not allowed to update the access level for the member, %s: %s" % (gitlab_user['name'], e)}) + else: + # remove the user from the project + try: + if not module.check_mode: + project.remove_user_from_project(gitlab_user_id, gitlab_project_id) + changed = True + changed_users.append("Successfully removed user, '%s', from the project" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'CHANGED', + 'msg': "Successfully removed user, '%s', from the project" % gitlab_user['name']}) + except (gitlab.exceptions.GitlabDeleteError) as e: + error = True + changed_users.append("Failed to removed user, '%s', from the project" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED', + 'msg': "Failed to remove user, '%s' from the project: %s" % (gitlab_user['name'], e)}) + + # if state = present and purge_users set delete users which are in members having give access level but not in gitlab_users + if state == 'present' and purge_users: + uppercase_names_in_gitlab_users_access = [] + for name in gitlab_users_access: + uppercase_names_in_gitlab_users_access.append(name['name'].upper()) + + for member in members: + if member.access_level in purge_users and member.username.upper() not in uppercase_names_in_gitlab_users_access: + try: + if not module.check_mode: + project.remove_user_from_project(member.id, gitlab_project_id) + changed = True + changed_users.append("Successfully removed user '%s', from project. Was not in given list" % member.username) + changed_data.append({'gitlab_user': member.username, 'result': 'CHANGED', + 'msg': "Successfully removed user '%s', from project. Was not in given list" % member.username}) + except (gitlab.exceptions.GitlabDeleteError) as e: + error = True + changed_users.append("Failed to removed user, '%s', from the project" % gitlab_user['name']) + changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED', + 'msg': "Failed to remove user, '%s' from the project: %s" % (gitlab_user['name'], e)}) + + if len(gitlab_users_access) == 1 and error: + # if single user given and an error occurred return error for list errors will be per user + module.fail_json(msg="FAILED: '%s '" % changed_users[0], result_data=changed_data) + elif error: + module.fail_json( + msg='FAILED: At least one given user/permission could not be set', result_data=changed_data) + + module.exit_json(changed=changed, msg='Successfully set memberships', result="\n".join(changed_users), result_data=changed_data) if __name__ == '__main__': diff --git a/tests/integration/targets/gitlab_project_members/defaults/main.yml b/tests/integration/targets/gitlab_project_members/defaults/main.yml index a31fc0f2d6..1b3ac19a47 100644 --- a/tests/integration/targets/gitlab_project_members/defaults/main.yml +++ b/tests/integration/targets/gitlab_project_members/defaults/main.yml @@ -3,3 +3,11 @@ gitlab_api_access_token: "token" gitlab_project: some_project username: some_user gitlab_access_level: developer +userlist: + - username1 + - username2 +dedicated_access_users: + - name: username1 + access_level: "developer" + - name: username2 + access_level: "maintainer" diff --git a/tests/integration/targets/gitlab_project_members/tasks/main.yml b/tests/integration/targets/gitlab_project_members/tasks/main.yml index c3330bae41..ade06d7ca2 100644 --- a/tests/integration/targets/gitlab_project_members/tasks/main.yml +++ b/tests/integration/targets/gitlab_project_members/tasks/main.yml @@ -19,7 +19,7 @@ api_token: "{{ gitlab_api_access_token }}" project: "{{ gitlab_project }}" gitlab_user: "{{ username }}" - state: absent + state: absent - name: Add a User to A GitLab Project community.general.gitlab_project_members: @@ -78,3 +78,46 @@ assert: that: - remove_gitlab_project_members_state_again is not changed + +- name: Add a list of Users to A GitLab Project + community.general.gitlab_project_members: + api_url: "{{ gitlab_server_url }}" + api_token: "{{ gitlab_api_access_token }}" + project: "{{ gitlab_project }}" + gitlab_user: "{{ userlist }}" + access_level: "{{ gitlab_access_level }}" + state: present + +- name: Remove a list of Users to A GitLab Project + community.general.gitlab_project_members:: + api_url: "{{ gitlab_server_url }}" + api_token: "{{ gitlab_api_access_token }}" + project: "{{ gitlab_project }}" + gitlab_user: "{{ userlist }}" + state: absent + +- name: Add a list of Users with Dedicated Access Levels to A GitLab Project + community.general.gitlab_project_members:: + api_url: "{{ gitlab_server_url }}" + api_token: "{{ gitlab_api_access_token }}" + project: "{{ gitlab_project }}" + gitlab_users_access: "{{ dedicated_access_users }}" + state: present + +- name: Remove a list of Users with Dedicated Access Levels to A GitLab Project + community.general.gitlab_project_members:: + api_url: "{{ gitlab_server_url }}" + api_token: "{{ gitlab_api_access_token }}" + project: "{{ gitlab_project }}" + gitlab_users_access: "{{ dedicated_access_users }}" + state: absent + +- name: Add a user, remove all others which might be on this access level + community.general.gitlab_project_members:: + api_url: "{{ gitlab_server_url }}" + api_token: "{{ gitlab_api_access_token }}" + project: "{{ gitlab_project }}" + gitlab_user: "{{ username }}" + access_level: "{{ gitlab_access_level }}" + pruge_users: "{{ gitlab_access_level }}" + state: present