Allow gitlab_runner to function for non-admin users (#1491)

* Allow gitlab_runner to function for non-admin users

* Fix errant whitespace

* Allow later python-gitlab versions

* gitlab_runner: Switch to feature instead of bugfix, add examples

* Fix version_added in gitlab_runner

* Cleanup documentation for gitlab_runner fix

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

Co-authored-by: Brendan Batliner <brendan.batliner@gmail.com>

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

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

* Revert docs change

* Clarify docs

* Clarify docs

Co-authored-by: Brendan Batliner <brendan.batliner@gmail.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/source_control/gitlab/gitlab_runner.py

@@ -57,6 +57,12 @@ options:
       - The registration token is used to register new runners.
     required: True
     type: str
+  owned:
+    description:
+      - Searches only runners available to the user when searching for existing, when false admin token required.
+    default: no
+    type: bool
+    version_added: 2.0.0
   active:
     description:
       - Define if the runners is immediately active after creation.
@@ -114,6 +120,14 @@ EXAMPLES = '''
     api_token: "{{ access_token }}"
     description: Docker Machine t1
     state: absent
+
+- name: Delete an owned runner as a non-admin
+  community.general.gitlab_runner:
+    api_url: https://gitlab.example.com/
+    api_token: "{{ access_token }}"
+    description: Docker Machine t1
+    owned: yes
+    state: absent
 '''
 
 RETURN = '''
@@ -246,18 +260,28 @@ class GitLabRunner(object):
     '''
     @param description Description of the runner
     '''
-    def findRunner(self, description):
-        runners = self._gitlab.runners.all(as_list=False)
+    def findRunner(self, description, owned=False):
+        if owned:
+            runners = self._gitlab.runners.list(as_list=False)
+        else:
+            runners = self._gitlab.runners.all(as_list=False)
+
         for runner in runners:
-            if (runner['description'] == description):
-                return self._gitlab.runners.get(runner['id'])
+            # python-gitlab 2.2 through at least 2.5 returns a list of dicts for list() instead of a Runner
+            # object, so we need to handle both
+            if hasattr(runner, "description"):
+                if (runner.description == description):
+                    return self._gitlab.runners.get(runner.id)
+            else:
+                if (runner['description'] == description):
+                    return self._gitlab.runners.get(runner['id'])
 
     '''
     @param description Description of the runner
     '''
-    def existsRunner(self, description):
+    def existsRunner(self, description, owned=False):
         # When runner exists, object will be stored in self.runnerObject.
-        runner = self.findRunner(description)
+        runner = self.findRunner(description, owned)
 
         if runner:
             self.runnerObject = runner
@@ -279,6 +303,7 @@ def main():
         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),
         tag_list=dict(type='list', default=[]),
         run_untagged=dict(type='bool', default=True),
         locked=dict(type='bool', default=False),
@@ -304,6 +329,7 @@ def main():
     )
 
     state = module.params['state']
+    owned = module.params['owned']
     runner_description = module.params['description']
     runner_active = module.params['active']
     tag_list = module.params['tag_list']
@@ -319,7 +345,7 @@ def main():
     gitlab_instance = gitlabAuthentication(module)
 
     gitlab_runner = GitLabRunner(module, gitlab_instance)
-    runner_exists = gitlab_runner.existsRunner(runner_description)
+    runner_exists = gitlab_runner.existsRunner(runner_description, owned)
 
     if state == 'absent':
         if runner_exists: