Add runners API documentation [ci-skip]
This commit is contained in:
Tomasz Maczukin
parent
53f775ae6d
commit
43c8daf3dc
2 changed files with 235 additions and 0 deletions
|
|
@ -32,6 +32,7 @@ following locations:
|
|||
- [Builds](builds.md)
|
||||
- [Build triggers](build_triggers.md)
|
||||
- [Build Variables](build_variables.md)
|
||||
- [Runners](runners.md)
|
||||
|
||||
## Authentication
|
||||
|
||||
|
|
|
|||
234
doc/api/runners.md
Normal file
234
doc/api/runners.md
Normal file
|
|
@ -0,0 +1,234 @@
|
|||
# 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
|
||||
}
|
||||
```
|
||||
Loading…
Reference in a new issue