diff options
Diffstat (limited to 'doc/api/runners.md')
-rw-r--r-- | doc/api/runners.md | 55 |
1 files changed, 37 insertions, 18 deletions
diff --git a/doc/api/runners.md b/doc/api/runners.md index c692faf9490..be69b762555 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -6,7 +6,15 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Runners API **(FREE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5. +[Pagination](rest/index.md#pagination) is available on the following API endpoints (they return 20 items by default): + +```plaintext +GET /runners +GET /runners/all +GET /runners/:id/jobs +GET /projects/:id/runners +GET /groups/:id/runners +``` ## Registration and authentication tokens @@ -33,7 +41,7 @@ GitLab and the runner are then connected. ## List owned runners -Get a list of specific runners available to the user. +Get a list of runners available to the user. ```plaintext GET /runners @@ -46,7 +54,7 @@ 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 return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -97,7 +105,7 @@ Example response: ## List all runners **(FREE SELF)** -Get a list of all runners in the GitLab instance (specific and shared). Access +Get a list of all runners in the GitLab instance (project and shared). Access is restricted to users with administrator access. ```plaintext @@ -184,7 +192,7 @@ Example response: ] ``` -To view more than the first 20 runners, use [pagination](index.md#pagination). +To view more than the first 20 runners, use [pagination](rest/index.md#pagination). ## Get runner's details @@ -325,7 +333,7 @@ Example response: ### Pause a runner -Pause a specific runner. +Pause a runner. ```plaintext PUT --form "paused=true" /runners/:runner_id @@ -462,8 +470,8 @@ 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](index.md#namespaced-path-encoding) owned by the authenticated user | -| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of runners to return, one of: `active`, `paused`, `online` and `offline`; showing all runners if none provided | | `type` | string | no | The type of runners to return, one of: `instance_type`, `group_type`, `project_type` | | `status` | string | no | The status of runners to return, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0 | | `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | @@ -514,7 +522,7 @@ Example response: ## Enable a runner in project -Enable an available specific runner in the project. +Enable an available project runner in the project. ```plaintext POST /projects/:id/runners @@ -522,7 +530,7 @@ POST /projects/:id/runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -548,7 +556,7 @@ Example response: ## Disable a runner from project -Disable a specific runner from the project. It works only if the project isn't +Disable a project 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 call to [delete a runner](#delete-a-runner) instead. @@ -558,7 +566,7 @@ DELETE /projects/:id/runners/:runner_id | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ```shell @@ -739,9 +747,10 @@ Validates authentication credentials for a registered runner. POST /runners/verify ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|-------------------------------------------------------------------------------| -| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| Attribute | Type | Required | Description | +|-------------|---------|----------|------------------------------------------------------------------------------------------------| +| `token` | string | yes | The runner's [authentication token](#registration-and-authentication-tokens). | +| `system_id` | string | no | The runner's system identifier. This attribute is required if the `token` starts with `glrt-`. | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \ @@ -755,13 +764,23 @@ Response: | 200 | Credentials are valid | | 403 | Credentials are invalid | +Example response: + +```json +{ + "id": 12345, + "token": "glrt-6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" +} +``` + ## Reset instance's runner registration token > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30942) in GitLab 14.3. > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for the GitLab instance. @@ -780,7 +799,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a project. @@ -799,7 +818,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \ > - [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/104691) in GitLab 15.7. WARNING: -This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 16.0. This change is a breaking change. +This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/383341) in GitLab 15.7 and is planned for removal in 17.0. This change is a breaking change. Reset the runner registration token for a group. |