From cb985b31f91be2619ee472b8e8ece57fa03c5965 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?L=C3=A9o=20GATELLIER?=
 <26511053+lgatellier@users.noreply.github.com>
Date: Fri, 10 May 2024 15:15:18 +0200
Subject: [PATCH] docs(gitlab_runner): improve docs and add examples (#8310)

---
 plugins/modules/gitlab_runner.py | 53 +++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 5 deletions(-)

diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py
index e6163a6b6c..96b3eb3fa4 100644
--- a/plugins/modules/gitlab_runner.py
+++ b/plugins/modules/gitlab_runner.py
@@ -15,17 +15,20 @@ DOCUMENTATION = '''
 module: gitlab_runner
 short_description: Create, modify and delete GitLab Runners
 description:
-  - Register, update and delete runners with the GitLab API.
+  - Register, update and delete runners on GitLab Server side with the GitLab API.
   - All operations are performed using the GitLab API v4.
-  - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html).
+  - For details, consult the full API documentation at U(https://docs.gitlab.com/ee/api/runners.html)
+    and U(https://docs.gitlab.com/ee/api/users.html#create-a-runner-linked-to-a-user).
   - A valid private API token is required for all operations. You can create as many tokens as you like using the GitLab web interface at
     U(https://$GITLAB_URL/profile/personal_access_tokens).
   - A valid registration token is required for registering a new runner.
     To create shared runners, you need to ask your administrator to give you this token.
     It can be found at U(https://$GITLAB_URL/admin/runners/).
+  - This module does not handle the C(gitlab-runner) process part, but only manages the runner on GitLab Server side through its API.
+    Once the module has created the runner, you may use the generated token to run C(gitlab-runner register) command
 notes:
   - To create a new runner at least the O(api_token), O(description) and O(api_url) options are required.
-  - Runners need to have unique descriptions.
+  - Runners need to have unique descriptions, since this attribute is used as key for idempotency
 author:
   - Samy Coenen (@SamyCoenen)
   - Guillaume Martinez (@Lunik)
@@ -153,7 +156,45 @@ options:
 '''
 
 EXAMPLES = '''
-- name: "Register runner"
+- name: Create an instance-level runner
+  community.general.gitlab_runner:
+    api_url: https://gitlab.example.com/
+    api_token: "{{ access_token }}"
+    description: Docker Machine t1
+    state: present
+    active: true
+    tag_list: ['docker']
+    run_untagged: false
+    locked: false
+  register: runner # Register module output to run C(gitlab-runner register) command in another task
+
+- name: Create a group-level runner
+  community.general.gitlab_runner:
+    api_url: https://gitlab.example.com/
+    api_token: "{{ access_token }}"
+    description: Docker Machine t1
+    state: present
+    active: true
+    tag_list: ['docker']
+    run_untagged: false
+    locked: false
+    group: top-level-group/subgroup
+  register: runner # Register module output to run C(gitlab-runner register) command in another task
+
+- name: Create a project-level runner
+  community.general.gitlab_runner:
+    api_url: https://gitlab.example.com/
+    api_token: "{{ access_token }}"
+    description: Docker Machine t1
+    state: present
+    active: true
+    tag_list: ['docker']
+    run_untagged: false
+    locked: false
+    project: top-level-group/subgroup/project
+  register: runner # Register module output to run C(gitlab-runner register) command in another task
+
+- name: "Register instance-level runner with registration token (deprecated)"
   community.general.gitlab_runner:
     api_url: https://gitlab.example.com/
     api_token: "{{ access_token }}"
@@ -164,6 +205,7 @@ EXAMPLES = '''
     tag_list: ['docker']
     run_untagged: false
     locked: false
+  register: runner # Register module output to run C(gitlab-runner register) command in another task
 
 - name: "Delete runner"
   community.general.gitlab_runner:
@@ -180,7 +222,7 @@ EXAMPLES = '''
     owned: true
     state: absent
 
-- name: Register runner for a specific project
+- name: "Register a project-level runner with registration token (deprecated)"
   community.general.gitlab_runner:
     api_url: https://gitlab.example.com/
     api_token: "{{ access_token }}"
@@ -188,6 +230,7 @@ EXAMPLES = '''
     description: MyProject runner
     state: present
     project: mygroup/mysubgroup/myproject
+  register: runner # Register module output to run C(gitlab-runner register) command in another task
 '''
 
 RETURN = '''