diff options
Diffstat (limited to 'doc/api/runners.md')
| -rw-r--r-- | doc/api/runners.md | 76 |
1 files changed, 54 insertions, 22 deletions
diff --git a/doc/api/runners.md b/doc/api/runners.md index 35c18649fec..2d91428d1c1 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -4,6 +4,29 @@ [ce-2640]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2640 +## Registration and authentication tokens + +There are two tokens to take into account when connecting a Runner with GitLab. + +| Token | Description | +| ----- | ----------- | +| Registration token | Token used to [register the Runner](https://docs.gitlab.com/runner/register/). It can be [obtained through GitLab](../ci/runners/README.md). | +| Authentication token | Token used to authenticate the Runner with the GitLab instance. It is obtained either automatically when [registering a Runner](https://docs.gitlab.com/runner/register/), or manually when [registering the Runner via the Runners API](#register-a-new-runner). | + +Here's an example of how the two tokens are used in Runner registration: + +1. You register the Runner via the GitLab API using a registration token, and an + authentication token is returned. +1. You use that authentication token and add it to the + [Runner's configuration file](https://docs.gitlab.com/runner/commands/#configuration-file): + + ```toml + [[runners]] + token = "<authentication_token>" + ``` + +GitLab and Runner are then connected. + ## List owned runners Get a list of specific runners available to the user. @@ -13,13 +36,15 @@ GET /runners GET /runners?scope=active GET /runners?type=project_type GET /runners?status=active +GET /runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|---------------------| +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| `tag_list` | Array[String] | no | List of of the runner's tags | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" @@ -62,13 +87,15 @@ GET /runners/all GET /runners/all?scope=online GET /runners/all?type=project_type GET /runners/all?status=active +GET /runners/all?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|---------------------| +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to show, one of: `specific`, `shared`, `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| `tag_list` | Array[String] | no | List of of the runner's tags | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all" @@ -252,6 +279,8 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## List runner's jobs +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15432) in GitLab 10.3. + List jobs that are being processed or were processed by specified Runner. ``` @@ -347,14 +376,16 @@ GET /projects/:id/runners GET /projects/:id/runners?scope=active GET /projects/:id/runners?type=project_type GET /projects/:id/runners?status=active +GET /projects/:id/runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | -| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | -| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| Attribute | Type | Required | Description | +|------------|----------------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type` | +| `status` | string | no | The status of runners to show, one of: `active`, `paused`, `online`, `offline` | +| `tag_list` | Array[String] | no | List of of the runner's tags | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" @@ -448,17 +479,18 @@ POST /runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Registration token ([Read how to obtain a token](../ci/runners/README.md)) | +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | | `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 | +| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | | `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" +curl --request POST "https://gitlab.example.com/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" ``` Response: @@ -486,10 +518,10 @@ DELETE /runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Runner's authentication token | +| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | ``` -curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=ebb6fc00521627750c8bb750f2490e" +curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>" ``` Response: @@ -508,10 +540,10 @@ POST /runners/verify | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `token` | string | yes | Runner's authentication token | +| `token` | string | yes | Runner's [authentication token](#registration-and-authentication-tokens). | ``` -curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=ebb6fc00521627750c8bb750f2490e" +curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>" ``` Response: |