diff options
author | Mark Fletcher <mark@gitlab.com> | 2018-01-16 08:29:48 +0000 |
---|---|---|
committer | Mark Fletcher <mark@gitlab.com> | 2018-05-10 15:53:43 +0100 |
commit | bdb420d863350008782ef33fa8893d66bb8bd1c2 (patch) | |
tree | 12e2bad5347a6a7462049ab7eba8776e8618931f /doc/api/runners.md | |
parent | 96b9c070ad102ec1004921ff318e2a0a591a5a9c (diff) | |
download | gitlab-ce-bdb420d863350008782ef33fa8893d66bb8bd1c2.tar.gz |
Expand documentation for Runners API
- Document Registation - POST `/runners/`
- Document Deletion - DELETE `/runners/`
- Document Verification - POST `/runners/verify/
Diffstat (limited to 'doc/api/runners.md')
-rw-r--r-- | doc/api/runners.md | 83 |
1 files changed, 83 insertions, 0 deletions
diff --git a/doc/api/runners.md b/doc/api/runners.md index f384ac57bfe..3ca07ce9795 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -411,3 +411,86 @@ DELETE /projects/:id/runners/:runner_id ``` curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9" ``` + +## Register a new Runner + +Register a new Runner for the instance. + +``` +POST /runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Registration token ([Read how to obtain a token](../ci/runners/README.md)) | +| `description`| string | no | Runner's description| +| `info` | hash | no | Runner's metadata | +| `active` | boolean| no | Whether the Runner is active | +| `locked` | boolean| no | Whether the Runner should be locked for current project | +| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs | +| `tag_list` | Array[String] | no | List of Runner's tags | +| `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | + +``` +curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=ipzXrMhuyyJPifUt6ANz" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 201 | Runner was created | + +Example response: + +```json +{ + "id": "12345", + "token": "6337ff461c94fd3fa32ba3b1ff4125" +} +``` + +## Delete a registered Runner + +Deletes a registed Runner. + +``` +DELETE /runners +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Runner's authentication token | + +``` +curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 204 | Runner was deleted | + +## Verify authentication for a registered Runner + +Validates authentication credentials for a registered Runner. + +``` +POST /runners/verify +``` + +| Attribute | Type | Required | Description | +|-------------|---------|----------|---------------------| +| `token` | string | yes | Runner's authentication token | + +``` +curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e" +``` + +Response: + +| Status | Description | +|-----------|---------------------------------| +| 200 | Credentials are valid | +| 403 | Credentials are invalid | |