diff options
Diffstat (limited to 'doc/api')
| -rw-r--r-- | doc/api/README.md | 1 | ||||
| -rw-r--r-- | doc/api/builds.md | 88 | ||||
| -rw-r--r-- | doc/api/runners.md | 322 |
3 files changed, 411 insertions, 0 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 9f3ad126320..7629ef294ac 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -32,6 +32,7 @@ following locations: - [Builds](builds.md) - [Build triggers](build_triggers.md) - [Build Variables](build_variables.md) +- [Runners](runners.md) ## Authentication diff --git a/doc/api/builds.md b/doc/api/builds.md index 43edb40e911..d3ce72e59fc 100644 --- a/doc/api/builds.md +++ b/doc/api/builds.md @@ -34,6 +34,10 @@ Example of response "coverage": null, "created_at": "2015-12-24T15:51:21.802Z", "download_url": null, + "artifacts_file": { + "filename": "artifacts.zip", + "size": 1000 + }, "finished_at": "2015-12-24T17:54:27.895Z", "id": 7, "name": "teaspoon", @@ -72,6 +76,7 @@ Example of response "coverage": null, "created_at": "2015-12-24T15:51:21.727Z", "download_url": null, + "artifacts_file": null, "finished_at": "2015-12-24T17:54:24.921Z", "id": 6, "name": "spinach:other", @@ -135,6 +140,7 @@ Example of response "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", "download_url": null, + "artifacts_file": null, "finished_at": "2016-01-11T10:14:09.526Z", "id": 69, "name": "rubocop", @@ -159,6 +165,7 @@ Example of response "coverage": null, "created_at": "2015-12-24T15:51:21.957Z", "download_url": null, + "artifacts_file": null, "finished_at": "2015-12-24T17:54:33.913Z", "id": 9, "name": "brakeman", @@ -220,6 +227,7 @@ Example of response "coverage": null, "created_at": "2015-12-24T15:51:21.880Z", "download_url": null, + "artifacts_file": null, "finished_at": "2015-12-24T17:54:31.198Z", "id": 8, "name": "rubocop", @@ -247,6 +255,34 @@ Example of response } ``` +## Get build artifacts + +> [Introduced][ce-2893] in GitLab 8.5 + +Get build artifacts of a project + +``` +GET /projects/:id/builds/:build_id/artifacts +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +``` +curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8/artifacts" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 200 | Serves the artifacts file | +| 404 | Build not found or no artifacts | + +[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 + ## Cancel a build Cancel a single build of a project @@ -280,6 +316,7 @@ Example of response "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", "download_url": null, + "artifacts_file": null, "finished_at": "2016-01-11T10:14:09.526Z", "id": 69, "name": "rubocop", @@ -326,6 +363,7 @@ Example of response "coverage": null, "created_at": "2016-01-11T10:13:33.506Z", "download_url": null, + "artifacts_file": null, "finished_at": null, "id": 69, "name": "rubocop", @@ -338,3 +376,53 @@ Example of response "user": null } ``` + +## Erase a build + +Erase a single build of a project (remove build artifacts and a build trace) + +``` +POST /projects/:id/builds/:build_id/erase +``` + +Parameters + +| Attribute | Type | required | Description | +|-------------|---------|----------|---------------------| +| `id` | integer | yes | The ID of a project | +| `build_id` | integer | yes | The ID of a build | + +Example of request + +``` +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/erase" +``` + +Example of response + +```json +{ + "commit": { + "author_email": "admin@example.com", + "author_name": "Administrator", + "created_at": "2015-12-24T16:51:14.000+01:00", + "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd", + "message": "Test the CI integration.", + "short_id": "0ff3ae19", + "title": "Test the CI integration." + }, + "coverage": null, + "download_url": null, + "id": 69, + "name": "rubocop", + "ref": "master", + "runner": null, + "stage": "test", + "created_at": "2016-01-11T10:13:33.506Z", + "started_at": "2016-01-11T10:13:33.506Z", + "finished_at": "2016-01-11T10:15:10.506Z", + "status": "failed", + "tag": false, + "user": null +} +``` diff --git a/doc/api/runners.md b/doc/api/runners.md new file mode 100644 index 00000000000..cc6c6b7cb2f --- /dev/null +++ b/doc/api/runners.md @@ -0,0 +1,322 @@ +# Runners API + +> [Introduced][ce-2640] in GitLab 8.5 + +[ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640 + +## 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 +} +``` |