diff options
Diffstat (limited to 'doc/api/runners.md')
| -rw-r--r-- | doc/api/runners.md | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/doc/api/runners.md b/doc/api/runners.md new file mode 100644 index 00000000000..8840b8abdcc --- /dev/null +++ b/doc/api/runners.md @@ -0,0 +1,318 @@ +# Runners API + +## List owned runners + +Get a list of specific runners available to the user. + +``` +GET /runners +GET /runners?scope=active +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `scope` | string | no | The scope of specific runners to show, one of: `active`, `paused`, `online`; showing all runners if none provided | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/runners" +``` + +Example response: + +```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 + } +] +``` + +## List all runners + +Get a list of all runners in the GitLab instance (specific and shared). Access +is restricted to users with `admin` privileges. + +``` +GET /runners/all +GET /runners/all?scope=online +``` + +| 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/all" +``` + +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 + } +] +``` + +## 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" +``` + +Example response: + +```json +{ + "active": true, + "architecture": null, + "description": "test-1-20150125", + "id": 6, + "is_shared": false, + "contacted_at": "2016-01-25T16:39:48.066Z", + "name": null, + "platform": null, + "projects": [ + { + "id": 1, + "name": "GitLab Community Edition", + "name_with_namespace": "GitLab.org / GitLab Community Edition", + "path": "gitlab-ce", + "path_with_namespace": "gitlab-org/gitlab-ce" + } + ], + "token": "205086a8e3b9a2b818ffac9b89d102", + "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" +``` + +Example response: + +```json +{ + "active": true, + "architecture": null, + "description": "test-1-20150125-test", + "id": 6, + "is_shared": false, + "contacted_at": "2016-01-25T16:39:48.066Z", + "name": null, + "platform": null, + "projects": [ + { + "id": 1, + "name": "GitLab Community Edition", + "name_with_namespace": "GitLab.org / GitLab Community Edition", + "path": "gitlab-ce", + "path_with_namespace": "gitlab-org/gitlab-ce" + } + ], + "token": "205086a8e3b9a2b818ffac9b89d102", + "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" +``` + +Example response: + +```json +{ + "active": true, + "description": "test-1-20150125-test", + "id": 6, + "is_shared": false, + "name": null, +} +``` + +## List project's runners + +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. + +``` +GET /projects/:id/runners +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/9/runners" +``` + +Example response: + +```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 an available specific runner in the project. + +``` +POST /projects/:id/runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `runner_id` | integer | yes | The ID of a runner | + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/project/9/runners" -F "runner_id=9" +``` + +Example response: + +```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 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. + +``` +DELETE /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" +``` + +Example response: + +```json +{ + "active": true, + "description": "test-2016-02-01", + "id": 9, + "is_shared": false, + "name": null +} +``` |