1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
#######
Runners
#######
Runners are external processes used to run CI jobs. They are deployed by the
administrator and registered to the GitLab instance.
Shared runners are available for all projects. Specific runners are enabled for
a list of projects.
Global runners (admin)
======================
Reference
---------
* v4 API:
+ :class:`gitlab.v4.objects.Runner`
+ :class:`gitlab.v4.objects.RunnerManager`
+ :attr:`gitlab.Gitlab.runners`
+ :class:`gitlab.v4.objects.RunnerAll`
+ :class:`gitlab.v4.objects.RunnerAllManager`
+ :attr:`gitlab.Gitlab.runners_all`
* GitLab API: https://docs.gitlab.com/api/runners
Examples
--------
Use the ``runners.list()`` and ``runners_all.list()`` methods to list runners.
``runners.list()`` - Get a list of specific runners available to the user
``runners_all.list()`` - Get a list of all runners in the GitLab instance
(specific and shared). Access is restricted to users with administrator access.
Both methods accept a ``scope`` parameter to filter the list. Allowed values
for this parameter are:
* ``active``
* ``paused``
* ``online``
* ``specific`` (``runners_all.list()`` only)
* ``shared`` (``runners_all.list()`` only)
.. note::
The returned objects hold minimal information about the runners. Use the
``get()`` method to retrieve detail about a runner.
Runners returned via ``runners_all.list()`` also cannot be manipulated
directly. You will need to use the ``get()`` method to create an editable
object.
::
# List owned runners
runners = gl.runners.list(get_all=True)
# List owned runners with a filter
runners = gl.runners.list(scope='active', get_all=True)
# List all runners in the GitLab instance (specific and shared), using a filter
runners = gl.runners_all.list(scope='paused', get_all=True)
Get a runner's detail::
runner = gl.runners.get(runner_id)
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 runners, which does not use
registration tokens.
The new endpoint can be called using ``gl.user.runners.create()`` after
authenticating with ``gl.auth()``.
Update a runner::
runner = gl.runners.get(runner_id)
runner.tag_list.append('new_tag')
runner.save()
Remove a runner::
gl.runners.delete(runner_id)
# or
runner.delete()
Remove a runner by its authentication token::
gl.runners.delete(token="runner-auth-token")
Verify a registered runner token::
try:
gl.runners.verify(runner_token)
print("Valid token")
except GitlabVerifyError:
print("Invalid token")
Project/Group runners
=====================
Reference
---------
* v4 API:
+ :class:`gitlab.v4.objects.ProjectRunner`
+ :class:`gitlab.v4.objects.ProjectRunnerManager`
+ :attr:`gitlab.v4.objects.Project.runners`
+ :class:`gitlab.v4.objects.GroupRunner`
+ :class:`gitlab.v4.objects.GroupRunnerManager`
+ :attr:`gitlab.v4.objects.Group.runners`
* GitLab API: https://docs.gitlab.com/api/runners
Examples
--------
List the runners for a project::
runners = project.runners.list(get_all=True)
Enable a specific runner for a project::
p_runner = project.runners.create({'runner_id': runner.id})
Disable a specific runner for a project::
project.runners.delete(runner.id)
Runner jobs
===========
Reference
---------
* v4 API:
+ :class:`gitlab.v4.objects.RunnerJob`
+ :class:`gitlab.v4.objects.RunnerJobManager`
+ :attr:`gitlab.v4.objects.Runner.jobs`
* GitLab API: https://docs.gitlab.com/api/runners
Examples
--------
List for jobs for a runner::
jobs = runner.jobs.list(get_all=True)
Filter the list using the jobs status::
# status can be 'running', 'success', 'failed' or 'canceled'
active_jobs = runner.jobs.list(status='running', get_all=True)
|
