Commit 43c8daf3 authored by Tomasz Maczukin's avatar Tomasz Maczukin

Add runners API documentation [ci-skip]

parent 53f775ae
......@@ -32,6 +32,7 @@ following locations:
- [Builds](builds.md)
- [Build triggers](build_triggers.md)
- [Build Variables](build_variables.md)
- [Runners](runners.md)
## Authentication
......
# Runners API
## List runners
Get a list of runners.
```
GET /runners
```
| 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 |
```
curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners"
```
```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
}
]
```
## Get runner's details
Get details of a runner.
```
GET /runners/:id
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
```
curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6"
```
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
"last_contact": "2016-01-25T16:39:48.066Z",
"name": null,
"platform": null,
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
"version": null
}
```
## Update runner's details
Update details of a runner.
```
PUT /runners/:id
```
| Attribute | Type | required | Description |
|---------------|---------|----------|---------------------|
| `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 |
```
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"
```
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"is_shared": false,
"last_contact": "2016-01-25T16:39:48.066Z",
"name": null,
"platform": null,
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
"version": null
}
```
## Remove a runner
Remove a runner.
```
DELETE /runners/:id
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a runner |
```
curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners/6"
```
```json
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"is_shared": false,
"last_contact": "2016-01-25T16:39:48.066Z",
"name": null,
"platform": null,
"revision": null,
"tag_list": [],
"version": null
}
```
## List project's runners
List all runners (*shared* and *specific*) available in project. Shared runners are listed if at least one shared runner
is defined **and** shared runners usage is enabled in project's settings.
```
GET /projects/:id/runners
```
| Attribute | Type | required | Description |
|-----------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
```
curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners"
```
```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
Enable available specific runner in project.
```
PUT /projects/:id/runners/:runner_id
```
| Attribute | Type | required | Description |
|-------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `runner_id` | integer | yes | The ID of a runner |
```
curl -X PUT -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners/9"
```
```json
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"is_shared": false,
"name": null
}
```
## Disable a runner from project
Disable a specific runner from project. It works only, if the project isn't an only project associated with the
specified runner. If so, then an error is returned and user should use the [remove a runner](#remove-a-runner) feature.
```
PUT /projects/:id/runners/:runner_id
```
| Attribute | Type | required | Description |
|-------------|---------|----------|---------------------|
| `id` | integer | yes | The ID of a project |
| `runner_id` | integer | yes | The ID of a runner |
```
curl -X DELETE -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners/9"
```
```json
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"is_shared": false,
"name": null
}
```
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment