Repository: ansible-collections/community.general

Issue:
gitlab_runner docs: Examples for new registration workflow
### Summary

In https://github.com/ansible-collections/community.general/issues/3742, support for the new GitLab Runner registration workflow was added (GitLab >= 16.0). The docs do still only cover "old" examples with a `registration_token`: https://docs.ansible.com/ansible/latest/collections/community/general/gitlab_runner_module.html#examples

Can you add examples on how to use this module without the `registration_token`, but with the new registration workflow? Could you further clarify, if this module only configures the "GitLab server" or (also) the "GitLab Runner server"? In other words, after using this module, do I still have to go to the GitLab Runner and execute `gitlab-runner register ...`?

### Issue Type

Documentation Report

### Component Name

gitlab_runner

### Ansible Version

```console (paste below)
$ ansible --version
ansible [core 2.15.10]
  config file = /home/user/.ansible.cfg
  configured module search path = ['/home/user/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/user/.local/lib/python3.9/site-packages/ansible
  ansible collection location = /home/user/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/user/.local/bin/ansible
  python version = 3.9.18 (main, Jan 24 2024, 00:00:00) [GCC 11.4.1 20231218 (Red Hat 11.4.1-3)] (/usr/bin/python3)
  jinja version = 3.1.3
  libyaml = True
```


### Community.general Version

```console (paste below)
$ ansible-galaxy collection list community.general
# /home/user/.local/lib/python3.9/site-packages/ansible_collections
Collection        Version
----------------- -------
community.general 8.5.0
```


### Configuration

```console (paste below)
$ ansible-config dump --only-changed
CONFIG_FILE() = /home/user/.ansible.cfg
DEFAULT_STDOUT_CALLBACK(/home/user/.ansible.cfg) = yaml
```


### OS / Environment

CentOS Stream 9

### Additional Information

_No response_

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:
Files identified in the description:
* [`plugins/modules/gitlab_runner.py`](https://github.com/ansible-collections/community.general/blob/main/plugins/modules/gitlab_runner.py)

If these files are incorrect, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->
cc @Lunik @SamyCoenen @Shaps @lgatellier @marwatk @metanovii @nejch @scodeman @sh0shin @suukit @waheedi @zanssa
[click here for bot help](https://github.com/ansible/ansibullbot/blob/devel/ISSUE_HELP.md)
<!--- boilerplate: notify --->

Resolving patch:
diff --git a/plugins/modules/gitlab_runner.py b/plugins/modules/gitlab_runner.py
--- a/plugins/modules/gitlab_runner.py
+++ b/plugins/modules/gitlab_runner.py
@@ -15,17 +15,20 @@
 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 @@
 '''
 
 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 @@
     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 @@
     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 @@
     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 = '''


Test patch: