BigW Consortium Gitlab

runners.md 7.36 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 --header "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 --header "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 --header "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 --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6" --form "description=test-1-20150125-test" --form "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 --request DELETE --header "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 --header "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 --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners" --form "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 --request DELETE --header "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
}
```