Get behavior of gitlab_project_members to the one of gitlab_group_members (#3319)

* Initial change to get behaviour of gitlab_project_members like the new gitlab_group_members

* added changelog

* linter: removed trainling whitespaces

* Update plugins/modules/source_control/gitlab/gitlab_project_members.py

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

* Update plugins/modules/source_control/gitlab/gitlab_project_members.py

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

* Update plugins/modules/source_control/gitlab/gitlab_project_members.py

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

* Update plugins/modules/source_control/gitlab/gitlab_project_members.py

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

* Update plugins/modules/source_control/gitlab/gitlab_project_members.py

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

* requested changes

* linter fixes

* undoing formatting changes to existing code

Co-authored-by: Max-Florian Bidlingmaier <Max.Bidlingmaier@konsolan.de>
Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Max Bidlingmaier <Max-Florian.Bidlingmaier@sap.com>

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).

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.
+            - A username or a list of usernames to add to/remove from the GitLab project.
-        required: true
+            - Mutually exclusive with I(gitlab_users_access).
-        type: str
+        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)
-            project = self._gitlab.projects.get(gitlab_project_id)
+        add_member = project.members.create(
-            add_member = project.members.create(
+            {'user_id': gitlab_user_id, 'access_level': access_level})
-                {'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))
 
     # 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 = self._gitlab.projects.get(gitlab_project_id)
+        project.members.delete(gitlab_user_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))
 
     # 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.access_level = access_level
+                member.save()
-                    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))
 
 
 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 purge_users:
-    if access_level:
+        purge_users = [access_level_int[level] for level in purge_users]
-        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]
 
     # 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
+    members = []
-    if not gitlab_user_id:
+    if module.params['gitlab_user'] is not None:
-        if state == 'absent':
+        gitlab_users_access = []
-            module.exit_json(changed=False, result="user '%s' not found, and thus also not part of the project" % gitlab_user)
+        gitlab_users = module.params['gitlab_user']
-        else:
+        for gl_user in gitlab_users:
-            module.fail_json(msg="user '%s' not found." % gitlab_user)
+            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)
+    if len(gitlab_users_access) == 1 and not purge_users:
-    is_user_a_member = project.is_user_a_member(members, gitlab_user_id)
+        # only single user given
-
+        members = [project.get_member_in_a_project(
-    # check if the user is a member in the project
+            gitlab_project_id, project.get_user_id(gitlab_users_access[0]['name']))]
-    if not is_user_a_member:
+        if members[0] is None:
-        if state == 'present':
+            members = []
-            # add user to the project
+    elif len(gitlab_users_access) > 1 or purge_users:
-            if not module.check_mode:
+        # list of users given
-                project.add_member_to_project(gitlab_user_id, gitlab_project_id, access_level)
+        members = project.get_members_in_a_project(gitlab_project_id)
-            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
     else:
-        if state == 'present':
+        module.exit_json(changed='OK', result="Nothing to do, please give at least one user or set purge_users true.",
-            # compare the access level
+                         result_data=[])
-            user_access_level = project.get_user_access_level(members, gitlab_user_id)
+
-            if user_access_level == access_level:
+    changed = False
-                module.exit_json(changed=False, result="User, '%s', is already a member in the project. No change to report" % gitlab_user)
+    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
+                error = True
-                if not module.check_mode:
+                changed_users.append("user '%s' not found." % gitlab_user['name'])
-                    project.update_user_access_level(members, gitlab_user_id, access_level)
+                changed_data.append({'gitlab_user': gitlab_user['name'], 'result': 'FAILED',
-                module.exit_json(changed=True, result="Successfully updated the access level for the user, '%s'" % gitlab_user)
+                                     '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 state == 'present':
-            if not module.check_mode:
+                # compare the access level
-                project.remove_user_from_project(gitlab_user_id, gitlab_project_id)
+                user_access_level = project.get_user_access_level(members, gitlab_user_id)
-            module.exit_json(changed=True, result="Successfully removed user, '%s', from the project" % gitlab_user)
+                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__':

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"

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