runners.md 7.27 KB
Newer Older
1
2
# Runners API

3
4
5
6
> [Introduced][ce-2640] in GitLab 8.5

[ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640

7
## List owned runners
8

9
Get a list of specific runners available to the user.
10
11
12

```
GET /runners
13
GET /runners?scope=active
14
15
```

16
| Attribute | Type    | Required | Description         |
17
|-----------|---------|----------|---------------------|
18
| `scope`   | string  | no       | The scope of specific runners to show, one of: `active`, `paused`, `online`; showing all runners if none provided |
19
20

```
21
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners"
22
23
```

24
25
Example response:

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
```json
[
    {
        "active": true,
        "description": "test-1-20150125",
        "id": 6,
        "is_shared": false,
        "name": null
    },
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
        "is_shared": false,
        "name": null
    }
]
```

45
46
## List all runners

47
48
Get a list of all runners in the GitLab instance (specific and shared). Access
is restricted to users with `admin` privileges.
49
50
51

```
GET /runners/all
52
GET /runners/all?scope=online
53
54
55
56
57
58
59
```

| Attribute | Type    | Required | Description         |
|-----------|---------|----------|---------------------|
| `scope`   | string  | no       | The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`; showing all runners if none provided |

```
60
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/all"
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
```

Example response:

```json
[
    {
        "active": true,
        "description": "shared-runner-1",
        "id": 1,
        "is_shared": true,
        "name": null
    },
    {
        "active": true,
        "description": "shared-runner-2",
        "id": 3,
        "is_shared": true,
        "name": null
    },
    {
        "active": true,
        "description": "test-1-20150125",
        "id": 6,
        "is_shared": false,
        "name": null
    },
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
        "is_shared": false,
        "name": null
    }
]
```

98
99
100
101
102
103
104
105
## Get runner's details

Get details of a runner.

```
GET /runners/:id
```

106
| Attribute | Type    | Required | Description         |
107
108
109
110
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

```
111
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6"
112
113
```

114
115
Example response:

116
117
118
119
120
121
122
```json
{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "is_shared": false,
123
    "contacted_at": "2016-01-25T16:39:48.066Z",
124
125
    "name": null,
    "platform": null,
126
127
128
    "projects": [
        {
            "id": 1,
129
            "name": "GitLab Community Edition",
130
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
131
            "path": "gitlab-ce",
132
            "path_with_namespace": "gitlab-org/gitlab-ce"
133
134
        }
    ],
135
    "token": "205086a8e3b9a2b818ffac9b89d102",
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql"
    ],
    "version": null
}
```

## Update runner's details

Update details of a runner.

```
PUT /runners/:id
```

153
| Attribute     | Type    | Required | Description         |
154
155
156
157
158
159
160
|---------------|---------|----------|---------------------|
| `id`          | integer | yes      | The ID of a runner  |
| `description` | string  | no       | The description of a runner |
| `active`      | boolean | no       | The state of a runner; can be set to `true` or `false` |
| `tag_list`    | array   | no       | The list of tags for a runner; put array of tags, that should be finally assigned to a runner |

```
161
curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6" -F "description=test-1-20150125-test" -F "tag_list=ruby,mysql,tag1,tag2"
162
163
```

164
165
Example response:

166
167
168
169
170
171
172
```json
{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "is_shared": false,
173
    "contacted_at": "2016-01-25T16:39:48.066Z",
174
175
    "name": null,
    "platform": null,
176
177
178
    "projects": [
        {
            "id": 1,
179
            "name": "GitLab Community Edition",
180
            "name_with_namespace": "GitLab.org / GitLab Community Edition",
181
            "path": "gitlab-ce",
182
            "path_with_namespace": "gitlab-org/gitlab-ce"
183
184
185
        }
    ],
    "token": "205086a8e3b9a2b818ffac9b89d102",
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
    "revision": null,
    "tag_list": [
        "ruby",
        "mysql",
        "tag1",
        "tag2"
    ],
    "version": null
}
```

## Remove a runner

Remove a runner.

```
DELETE /runners/:id
```

205
| Attribute | Type    | Required | Description         |
206
207
208
209
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a runner  |

```
210
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6"
211
212
```

213
214
Example response:

215
216
217
218
219
220
221
222
223
224
225
226
```json
{
    "active": true,
    "description": "test-1-20150125-test",
    "id": 6,
    "is_shared": false,
    "name": null,
}
```

## List project's runners

227
228
229
List all runners (specific and shared) available in the project. Shared runners
are listed if at least one shared runner is defined **and** shared runners
usage is enabled in the project's settings.
230
231
232
233
234

```
GET /projects/:id/runners
```

235
| Attribute | Type    | Required | Description         |
236
237
238
239
|-----------|---------|----------|---------------------|
| `id`      | integer | yes      | The ID of a project |

```
240
curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners"
241
242
```

243
244
Example response:

245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
```json
[
    {
        "active": true,
        "description": "test-2-20150125",
        "id": 8,
        "is_shared": false,
        "name": null
    },
    {
        "active": true,
        "description": "development_runner",
        "id": 5,
        "is_shared": true,
        "name": null
    }
]
```

## Enable a runner in project

266
Enable an available specific runner in the project.
267
268

```
269
POST /projects/:id/runners
270
271
```

272
| Attribute   | Type    | Required | Description         |
273
274
275
276
277
|-------------|---------|----------|---------------------|
| `id`        | integer | yes      | The ID of a project |
| `runner_id` | integer | yes      | The ID of a runner  |

```
278
curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners" -F "runner_id=9"
279
280
```

281
282
Example response:

283
284
285
286
287
288
289
290
291
292
293
294
```json
{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "is_shared": false,
    "name": null
}
```

## Disable a runner from project

295
296
297
Disable a specific runner from the project. It works only if the project isn't
the only project associated with the specified runner. If so, an error is
returned. Use the [Remove a runner](#remove-a-runner) call instead.
298
299

```
300
DELETE /projects/:id/runners/:runner_id
301
302
```

303
| Attribute   | Type    | Required | Description         |
304
305
306
307
308
|-------------|---------|----------|---------------------|
| `id`        | integer | yes      | The ID of a project |
| `runner_id` | integer | yes      | The ID of a runner  |

```
309
curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners/9"
310
311
```

312
313
Example response:

314
315
316
317
318
319
320
321
322
```json
{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "is_shared": false,
    "name": null
}
```