Add additional auth support to Gitlab (#705) (#3918) (#3929)

* Add additional auth support to Gitlab (#705)

- removed unused imports from module_utils.gitlab
- fix bug in gitlab_project to check if avatar_path is provided

* add doc_fragment and argument_spec for gitlab auth

* doc fixes and remove avatar_path bug fix

* small doc changes, pass validate_certs to requests call

* update changelog

(cherry picked from commit 52ad0a5fbb)

Co-authored-by: Josh <josham@users.noreply.github.com>

changelogs/fragments/705-gitlab-auth-support.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - gitlab - add more token authentication support with the new options ``api_oauth_token`` and ``api_job_token`` (https://github.com/ansible-collections/community.general/issues/705).

plugins/doc_fragments/gitlab.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Standard files documentation fragment
+    DOCUMENTATION = r'''
+requirements:
+  - requests (Python library U(https://pypi.org/project/requests/))
+
+options:
+  api_token:
+    description:
+      - GitLab access token with API permissions.
+    type: str
+  api_oauth_token:
+    description:
+      - GitLab OAuth token for logging in.
+    type: str
+    version_added: 4.2.0
+  api_job_token:
+    description:
+      - GitLab CI job token for logging in.
+    type: str
+    version_added: 4.2.0
+'''

plugins/module_utils/gitlab.py

@@ -7,29 +7,40 @@
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
-import json
 from distutils.version import StrictVersion
 
 from ansible.module_utils.basic import missing_required_lib
-from ansible.module_utils.urls import fetch_url
 from ansible.module_utils.common.text.converters import to_native
 
 try:
     from urllib import quote_plus  # Python 2.X
+    from urlparse import urljoin
 except ImportError:
-    from urllib.parse import quote_plus  # Python 3+
+    from urllib.parse import quote_plus, urljoin  # Python 3+
 
 import traceback
 
 GITLAB_IMP_ERR = None
 try:
     import gitlab
+    import requests
     HAS_GITLAB_PACKAGE = True
 except Exception:
     GITLAB_IMP_ERR = traceback.format_exc()
     HAS_GITLAB_PACKAGE = False
 
 
+def auth_argument_spec(spec=None):
+    arg_spec = (dict(
+        api_token=dict(type='str', no_log=True),
+        api_oauth_token=dict(type='str', no_log=True),
+        api_job_token=dict(type='str', no_log=True),
+    ))
+    if spec:
+        arg_spec.update(spec)
+    return arg_spec
+
+
 def find_project(gitlab_instance, identifier):
     try:
         project = gitlab_instance.projects.get(identifier)
@@ -58,6 +69,8 @@ def gitlab_authentication(module):
     gitlab_user = module.params['api_username']
     gitlab_password = module.params['api_password']
     gitlab_token = module.params['api_token']
+    gitlab_oauth_token = module.params['api_oauth_token']
+    gitlab_job_token = module.params['api_job_token']
 
     if not HAS_GITLAB_PACKAGE:
         module.fail_json(msg=missing_required_lib("python-gitlab"), exception=GITLAB_IMP_ERR)
@@ -70,7 +83,16 @@ def gitlab_authentication(module):
             gitlab_instance = gitlab.Gitlab(url=gitlab_url, ssl_verify=validate_certs, email=gitlab_user, password=gitlab_password,
                                             private_token=gitlab_token, api_version=4)
         else:
-            gitlab_instance = gitlab.Gitlab(url=gitlab_url, ssl_verify=validate_certs, private_token=gitlab_token, api_version=4)
+            # We can create an oauth_token using a username and password
+            # https://docs.gitlab.com/ee/api/oauth2.html#authorization-code-flow
+            if gitlab_user:
+                data = {'grant_type': 'password', 'username': gitlab_user, 'password': gitlab_password}
+                resp = requests.post(urljoin(gitlab_url, "oauth/token"), data=data, verify=validate_certs)
+                resp_data = resp.json()
+                gitlab_oauth_token = resp_data["access_token"]
+
+            gitlab_instance = gitlab.Gitlab(url=gitlab_url, ssl_verify=validate_certs, private_token=gitlab_token,
+                                            oauth_token=gitlab_oauth_token, job_token=gitlab_job_token, api_version=4)
 
         gitlab_instance.auth()
     except (gitlab.exceptions.GitlabAuthenticationError, gitlab.exceptions.GitlabGetError) as e:

plugins/modules/source_control/gitlab/gitlab_branch.py

@@ -18,7 +18,8 @@ requirements:
   - python >= 2.7
   - python-gitlab >= 2.3.0
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
   state:
@@ -27,11 +28,6 @@ options:
     default: present
     type: str
     choices: ["present", "absent"]
-  api_token:
-    description:
-      - GitLab access token with API permissions.
-    required: true
-    type: str
   project:
     description:
       - The path or name of the project.
@@ -87,7 +83,7 @@ except Exception:
     GITLAB_IMP_ERR = traceback.format_exc()
     HAS_GITLAB_PACKAGE = False
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 
 class GitlabBranch(object):
@@ -119,8 +115,8 @@ class GitlabBranch(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(
-        api_token=dict(type='str', required=True, no_log=True),
         project=dict(type='str', required=True),
         branch=dict(type='str', required=True),
         ref_branch=dict(type='str', required=False),
@@ -131,13 +127,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         required_if=[
             ['state', 'present', ['ref_branch'], True],

plugins/modules/source_control/gitlab/gitlab_deploy_key.py

@@ -14,7 +14,7 @@ DOCUMENTATION = '''
 module: gitlab_deploy_key
 short_description: Manages GitLab project deploy keys.
 description:
-     - Adds, updates and removes project deploy keys
+  - Adds, updates and removes project deploy keys
 author:
   - Marcus Watkins (@marwatk)
   - Guillaume Martinez (@Lunik)
@@ -22,13 +22,10 @@ requirements:
   - python >= 2.7
   - python-gitlab python module
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - GitLab token for logging in.
-    type: str
   project:
     description:
       - Id or Full path of project in the form of group/name.
@@ -126,7 +123,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import find_project, gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, find_project, gitlab_authentication
 
 
 class GitLabDeployKey(object):
@@ -238,8 +235,8 @@ class GitLabDeployKey(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         state=dict(type='str', default="present", choices=["absent", "present"]),
         project=dict(type='str', required=True),
         key=dict(type='str', required=True, no_log=False),
@@ -251,13 +248,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token']
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password']
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True,
     )

plugins/modules/source_control/gitlab/gitlab_group.py

@@ -22,13 +22,10 @@ requirements:
   - python >= 2.7
   - python-gitlab python module
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - GitLab token for logging in.
-    type: str
   name:
     description:
       - Name of the group you want to create.
@@ -175,7 +172,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import find_group, gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, find_group, gitlab_authentication
 
 
 class GitLabGroup(object):
@@ -309,8 +306,8 @@ class GitLabGroup(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         name=dict(type='str', required=True),
         path=dict(type='str'),
         description=dict(type='str'),
@@ -328,13 +325,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True,
     )

plugins/modules/source_control/gitlab/gitlab_group_members.py

@@ -12,78 +12,76 @@ DOCUMENTATION = r'''
 module: gitlab_group_members
 short_description: Manage group members on GitLab Server
 description:
-    - This module allows to add and remove members to/from a group, or change a member's access level in a group on GitLab.
+  - This module allows to add and remove members to/from a group, or change a member's access level in a group on GitLab.
 version_added: '1.2.0'
 author: Zainab Alsaffar (@zanssa)
 requirements:
-    - python-gitlab python module <= 1.15.0
+  - python-gitlab python module <= 1.15.0
-    - administrator rights on the GitLab server
+  - administrator rights on the GitLab server
-extends_documentation_fragment: community.general.auth_basic
+extends_documentation_fragment:
+  - community.general.auth_basic
+  - community.general.gitlab
+
 options:
-    api_token:
+  gitlab_group:
-        description:
+    description:
-            - A personal access token to authenticate with the GitLab API.
+      - The C(full_path) of the GitLab group the member is added to/removed from.
-        required: true
+      - Setting this to C(name) or C(path) is deprecated and will be removed in community.general 6.0.0. Use C(full_path) instead.
+    required: true
+    type: str
+  gitlab_user:
+    description:
+      - A username or a list of usernames to add to/remove from the GitLab group.
+      - 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.
+      - Mutually exclusive with I(gitlab_users_access).
+    type: str
+    choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
+  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 group.
+    type: list
+    elements: dict
+    suboptions:
+      name:
+        description: A username or a list of usernames to add to/remove from the GitLab group.
         type: str
-    gitlab_group:
-        description:
-            - The C(full_path) of the GitLab group the member is added to/removed from.
-            - Setting this to C(name) or C(path) is deprecated and will be removed in community.general 6.0.0. Use C(full_path) instead.
         required: true
-        type: str
+      access_level:
-    gitlab_user:
         description:
-            - A username or a list of usernames to add to/remove from the GitLab group.
+          - The access level for the user.
-            - Mutually exclusive with I(gitlab_users_access).
+          - Required if I(state=present), user state is set to present.
-        type: list
-        elements: str
-    access_level:
-        description:
-            - The access level for the user.
-            - Required if I(state=present), user state is set to present.
-            - Mutually exclusive with I(gitlab_users_access).
         type: str
         choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
-    gitlab_users_access:
+        required: true
-        description:
+    version_added: 3.6.0
-            - Provide a list of user to access level mappings.
+  state:
-            - Every dictionary in this list specifies a user (by username) and the access level the user should have.
+    description:
-            - Mutually exclusive with I(gitlab_user) and I(access_level).
+      - State of the member in the group.
-            - Use together with I(purge_users) to remove all users not specified here from the group.
+      - On C(present), it adds a user to a GitLab group.
-        type: list
+      - On C(absent), it removes a user from a GitLab group.
-        elements: dict
+    choices: ['present', 'absent']
-        suboptions:
+    default: 'present'
-            name:
+    type: str
-                description: A username or a list of usernames to add to/remove from the GitLab group.
+  purge_users:
-                type: str
+    description:
-                required: true
+      - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list.
-            access_level:
+        If omitted do not purge orphaned members.
-                description:
+      - Is only used when I(state=present).
-                    - The access level for the user.
+    type: list
-                    - Required if I(state=present), user state is set to present.
+    elements: str
-                type: str
+    choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
-                choices: ['guest', 'reporter', 'developer', 'maintainer', 'owner']
+    version_added: 3.6.0
-                required: true
-        version_added: 3.6.0
-    state:
-        description:
-            - State of the member in the group.
-            - On C(present), it adds a user to a GitLab group.
-            - On C(absent), it removes a user from a GitLab group.
-        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', 'owner']
-        version_added: 3.6.0
 notes:
-    - Supports C(check_mode).
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = r'''
@@ -155,7 +153,7 @@ RETURN = r''' # '''
 from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 import traceback
 
@@ -241,8 +239,8 @@ class GitLabGroup(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', required=True, no_log=True),
         gitlab_group=dict(type='str', required=True),
         gitlab_user=dict(type='list', elements='str'),
         state=dict(type='str', default='present', choices=['present', 'absent']),
@@ -262,16 +260,19 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
             ['gitlab_user', 'gitlab_users_access'],
             ['access_level', 'gitlab_users_access'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
             ['gitlab_user', 'access_level'],
         ],
         required_one_of=[
-            ['api_username', 'api_token'],
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token'],
             ['gitlab_user', 'gitlab_users_access'],
         ],
         required_if=[

plugins/modules/source_control/gitlab/gitlab_group_variable.py

@@ -24,6 +24,7 @@ requirements:
   - python-gitlab python module
 extends_documentation_fragment:
   - community.general.auth_basic
+  - community.general.gitlab
 
 options:
   state:
@@ -32,11 +33,6 @@ options:
     default: present
     type: str
     choices: ["present", "absent"]
-  api_token:
-    description:
-      - GitLab access token with API permissions.
-    required: true
-    type: str
   group:
     description:
       - The path and name of the group.
@@ -144,7 +140,7 @@ except Exception:
     GITLAB_IMP_ERR = traceback.format_exc()
     HAS_GITLAB_PACKAGE = False
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 
 class GitlabGroupVariables(object):
@@ -268,8 +264,8 @@ def native_python_main(this_gitlab, purge, var_list, state, module):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(
-        api_token=dict(type='str', required=True, no_log=True),
         group=dict(type='str', required=True),
         purge=dict(type='bool', required=False, default=False),
         vars=dict(type='dict', required=False, default=dict(), no_log=True),
@@ -280,13 +276,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True
     )

plugins/modules/source_control/gitlab/gitlab_hook.py

@@ -15,7 +15,7 @@ DOCUMENTATION = '''
 module: gitlab_hook
 short_description: Manages GitLab project hooks.
 description:
-     - Adds, updates and removes project hook
+  - Adds, updates and removes project hook
 author:
   - Marcus Watkins (@marwatk)
   - Guillaume Martinez (@Lunik)
@@ -23,13 +23,10 @@ requirements:
   - python >= 2.7
   - python-gitlab python module
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - GitLab token for logging in.
-    type: str
   project:
     description:
       - Id or Full path of the project in the form of group/name.
@@ -176,7 +173,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import find_project, gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, find_project, gitlab_authentication
 
 
 class GitLabHook(object):
@@ -297,8 +294,8 @@ class GitLabHook(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         state=dict(type='str', default="present", choices=["absent", "present"]),
         project=dict(type='str', required=True),
         hook_url=dict(type='str', required=True),
@@ -319,13 +316,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token']
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password']
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True,
     )

plugins/modules/source_control/gitlab/gitlab_project.py

@@ -23,13 +23,10 @@ requirements:
   - python >= 2.7
   - python-gitlab python module
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - GitLab token for logging in.
-    type: str
   group:
     description:
       - Id or the full path of the group of which this projects belongs to.
@@ -209,6 +206,19 @@ EXAMPLES = r'''
     initialize_with_readme: true
     state: present
   delegate_to: localhost
+
+- name: get the initial root password
+  ansible.builtin.shell: |
+    grep 'Password:' /etc/gitlab/initial_root_password | sed -e 's/Password\: \(.*\)/\1/'
+  register: initial_root_password
+
+- name: Create a GitLab Project using a username/password via oauth_token
+  community.general.gitlab_project:
+    api_url: https://gitlab.example.com/
+    api_username: root
+    api_password: "{{ initial_root_password }}"
+    name: my_second_project
+    group: "10481470"
 '''
 
 RETURN = r'''
@@ -249,7 +259,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import find_group, find_project, gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, find_group, find_project, gitlab_authentication
 
 
 class GitLabProject(object):
@@ -386,8 +396,8 @@ class GitLabProject(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         group=dict(type='str'),
         name=dict(type='str', required=True),
         path=dict(type='str'),
@@ -419,14 +429,17 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
             ['group', 'username'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True,
     )

plugins/modules/source_control/gitlab/gitlab_project_members.py

@@ -14,95 +14,75 @@ module: gitlab_project_members
 short_description: Manage project members on GitLab Server
 version_added: 2.2.0
 description:
-    - This module allows to add and remove members to/from a project, or change a member's access level in a project on GitLab.
+  - This module allows to add and remove members to/from a project, or change a member's access level in a project on GitLab.
 author:
-    - Sergey Mikhaltsov (@metanovii)
+  - Sergey Mikhaltsov (@metanovii)
-    - Zainab Alsaffar (@zanssa)
+  - Zainab Alsaffar (@zanssa)
 requirements:
-    - python-gitlab python module <= 1.15.0
+  - python-gitlab python module <= 1.15.0
-    - owner or maintainer rights to project on the GitLab server
+  - owner or maintainer rights to project on the GitLab server
+extends_documentation_fragment:
+  - community.general.auth_basic
+  - community.general.gitlab
+
 options:
-    api_token:
+  project:
-        description:
+    description:
-            - A personal access token to authenticate with the GitLab API.
+      - The name (or full path) of the GitLab project the member is added to/removed from.
+    required: true
+    type: str
+  gitlab_user:
+    description:
+      - 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
-        type: str
+      access_level:
-    validate_certs:
         description:
-            - Whether or not to validate TLS/SSL certificates when supplying a HTTPS endpoint.
+          - The access level for the user.
-            - Should only be set to C(false) if you can guarantee that you are talking to the correct server
+          - Required if I(state=present), user state is set to present.
-              and no man-in-the-middle attack can happen.
-        default: true
-        type: bool
-    api_username:
-        description:
-            - The username to use for authentication against the API.
-        type: str
-    api_password:
-        description:
-            - The password to use for authentication against the API.
-        type: str
-    api_url:
-        description:
-            - The resolvable endpoint for the API.
-        type: str
-    project:
-        description:
-            - The name (or full path) of the GitLab project the member is added to/removed from.
-        required: true
-        type: str
-    gitlab_user:
-        description:
-            - 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:
+        required: true
-        description:
+    version_added: 3.7.0
-            - Provide a list of user to access level mappings.
+  state:
-            - Every dictionary in this list specifies a user (by username) and the access level the user should have.
+    description:
-            - Mutually exclusive with I(gitlab_user) and I(access_level).
+      - State of the member in the project.
-            - Use together with I(purge_users) to remove all users not specified here from the project.
+      - On C(present), it adds a user to a GitLab project.
-        type: list
+      - On C(absent), it removes a user from a GitLab project.
-        elements: dict
+    choices: ['present', 'absent']
-        suboptions:
+    default: 'present'
-            name:
+    type: str
-                description: A username or a list of usernames to add to/remove from the GitLab project.
+  purge_users:
-                type: str
+    description:
-                required: true
+      - Adds/remove users of the given access_level to match the given I(gitlab_user)/I(gitlab_users_access) list.
-            access_level:
+        If omitted do not purge orphaned members.
-                description:
+      - Is only used when I(state=present).
-                    - The access level for the user.
+    type: list
-                    - Required if I(state=present), user state is set to present.
+    elements: str
-                type: str
+    choices: ['guest', 'reporter', 'developer', 'maintainer']
-                choices: ['guest', 'reporter', 'developer', 'maintainer']
+    version_added: 3.7.0
-                required: true
-        version_added: 3.7.0
-    state:
-        description:
-            - State of the member in the project.
-            - On C(present), it adds a user to a GitLab project.
-            - On C(absent), it removes a user from a GitLab project.
-        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).
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = r'''
@@ -176,7 +156,7 @@ RETURN = r''' # '''
 from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 import traceback
 
@@ -257,8 +237,8 @@ class GitLabProjectMembers(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', required=True, no_log=True),
         project=dict(type='str', required=True),
         gitlab_user=dict(type='list', elements='str'),
         state=dict(type='str', default='present', choices=['present', 'absent']),
@@ -280,7 +260,10 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
             ['gitlab_user', 'gitlab_users_access'],
             ['access_level', 'gitlab_users_access'],
         ],
@@ -289,7 +272,7 @@ def main():
             ['gitlab_user', 'access_level'],
         ],
         required_one_of=[
-            ['api_username', 'api_token'],
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token'],
             ['gitlab_user', 'gitlab_users_access'],
         ],
         required_if=[

plugins/modules/source_control/gitlab/gitlab_project_variable.py

@@ -20,7 +20,8 @@ requirements:
   - python >= 2.7
   - python-gitlab python module
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
   state:
@@ -30,11 +31,6 @@ options:
     default: present
     type: str
     choices: ["present", "absent"]
-  api_token:
-    description:
-      - GitLab access token with API permissions.
-    required: true
-    type: str
   project:
     description:
       - The path and name of the project.
@@ -143,7 +139,7 @@ except Exception:
     GITLAB_IMP_ERR = traceback.format_exc()
     HAS_GITLAB_PACKAGE = False
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 
 class GitlabProjectVariables(object):
@@ -270,8 +266,8 @@ def native_python_main(this_gitlab, purge, var_list, state, module):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(
-        api_token=dict(type='str', required=True, no_log=True),
         project=dict(type='str', required=True),
         purge=dict(type='bool', required=False, default=False),
         vars=dict(type='dict', required=False, default=dict(), no_log=True),
@@ -282,13 +278,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True
     )

plugins/modules/source_control/gitlab/gitlab_protected_branch.py

@@ -18,7 +18,8 @@ requirements:
   - python >= 2.7
   - python-gitlab >= 2.3.0
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
   state:
@@ -27,11 +28,6 @@ options:
     default: present
     type: str
     choices: ["present", "absent"]
-  api_token:
-    description:
-      - GitLab access token with API permissions.
-    required: true
-    type: str
   project:
     description:
       - The path and name of the project.
@@ -87,7 +83,7 @@ except Exception:
     GITLAB_IMP_ERR = traceback.format_exc()
     HAS_GITLAB_PACKAGE = False
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 
 class GitlabProtectedBranch(object):
@@ -141,8 +137,8 @@ class GitlabProtectedBranch(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(
-        api_token=dict(type='str', required=True, no_log=True),
         project=dict(type='str', required=True),
         name=dict(type='str', required=True),
         merge_access_levels=dict(type='str', default="maintainer", choices=["maintainer", "developer", "nobody"]),
@@ -154,13 +150,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True
     )

plugins/modules/source_control/gitlab/gitlab_runner.py

@@ -32,13 +32,10 @@ requirements:
   - python >= 2.7
   - python-gitlab >= 1.5.0
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - Your private token to interact with the GitLab API.
-    type: str
   project:
     description:
       - ID or full path of the project in the form of group/name.
@@ -186,7 +183,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, gitlab_authentication
 
 try:
     cmp
@@ -323,8 +320,8 @@ class GitLabRunner(object):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         description=dict(type='str', required=True, aliases=["name"]),
         active=dict(type='bool', default=True),
         owned=dict(type='bool', default=False),
@@ -342,13 +339,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token'],
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token'],
         ],
         required_if=[
             ('state', 'present', ['registration_token']),

plugins/modules/source_control/gitlab/gitlab_user.py

@@ -30,13 +30,10 @@ requirements:
   - python-gitlab python module
   - administrator rights on the GitLab server
 extends_documentation_fragment:
-- community.general.auth_basic
+  - community.general.auth_basic
+  - community.general.gitlab
 
 options:
-  api_token:
-    description:
-      - GitLab token for logging in.
-    type: str
   name:
     description:
       - Name of the user you want to create.
@@ -238,7 +235,7 @@ from ansible.module_utils.api import basic_auth_argument_spec
 from ansible.module_utils.basic import AnsibleModule, missing_required_lib
 from ansible.module_utils.common.text.converters import to_native
 
-from ansible_collections.community.general.plugins.module_utils.gitlab import find_group, gitlab_authentication
+from ansible_collections.community.general.plugins.module_utils.gitlab import auth_argument_spec, find_group, gitlab_authentication
 
 
 class GitLabUser(object):
@@ -579,8 +576,8 @@ def sanitize_arguments(arguments):
 
 def main():
     argument_spec = basic_auth_argument_spec()
+    argument_spec.update(auth_argument_spec())
     argument_spec.update(dict(
-        api_token=dict(type='str', no_log=True),
         name=dict(type='str'),
         state=dict(type='str', default="present", choices=["absent", "present", "blocked", "unblocked"]),
         username=dict(type='str', required=True),
@@ -603,13 +600,16 @@ def main():
         argument_spec=argument_spec,
         mutually_exclusive=[
             ['api_username', 'api_token'],
-            ['api_password', 'api_token'],
+            ['api_username', 'api_oauth_token'],
+            ['api_username', 'api_job_token'],
+            ['api_token', 'api_oauth_token'],
+            ['api_token', 'api_job_token'],
         ],
         required_together=[
             ['api_username', 'api_password'],
         ],
         required_one_of=[
-            ['api_username', 'api_token']
+            ['api_username', 'api_token', 'api_oauth_token', 'api_job_token']
         ],
         supports_check_mode=True,
         required_if=(