docs(users): Add new runner creation examples

lgatellier · lgatellier · commit fd02584865cc · 2023-08-19T10:37:56.000+02:00
diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst
@@ -71,6 +71,14 @@ Register a new runner::
 
     runner = gl.runners.create({'token': secret_token})
 
+.. note::
+
+   A new runner registration workflow has been introduced since GitLab 16.0. This new
+   workflow comes with a new API endpoint to create runner, which does not use
+   registration tokens.
+
+   The new endpoint can be called using ``user_runners.create()``.
+
 Update a runner::
 
     runner = gl.runners.get(runner_id)
diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst
@@ -456,3 +456,60 @@ Get the users activities::
         query_parameters={'from': '2018-07-01'},
         get_all=True,
     )
+
+Create new runner
+=================
+
+References
+----------
+
+* New runner registration API endpoint (see `Migrating to the new runner registration workflow <https://docs.gitlab.com/ee/ci/runners/new_creation_workflow.html#creating-runners-programmatically>`_)
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.UserRunner`
+  + :class:`gitlab.v4.objects.UserRunnerManager`
+  + :attr:`gitlab.Gitlab.user_runners`
+
+* GitLab API : https://docs.gitlab.com/ee/api/users.html#create-a-runner
+
+Examples
+--------
+
+Create an instance-wide runner::
+
+    runner = gl.user_runners.create({
+        "runner_type": "instance_type",
+        "description": "My brand new runner",
+        "paused": True,
+        "locked": False,
+        "run_untagged": True
+        "tag_list": ["linux", "docker", "testing"],
+        "access_level": "not_protected"
+    })
+
+Create a group runner::
+
+    runner = gl.user_runners.create({
+        "runner_type": "group_type",
+        "group_id": 12345678,
+        "description": "My brand new runner",
+        "paused": True,
+        "locked": False,
+        "run_untagged": True
+        "tag_list": ["linux", "docker", "testing"],
+        "access_level": "not_protected"
+    })
+
+Create a project runner::
+
+    runner = gl.user_runners.create({
+        "runner_type": "project_type",
+        "group_id": 987564321,
+        "description": "My brand new runner",
+        "paused": True,
+        "locked": False,
+        "run_untagged": True
+        "tag_list": ["linux", "docker", "testing"],
+        "access_level": "not_protected"
+    })
