diff options
Diffstat (limited to 'doc/api/runners.md')
| -rw-r--r-- | doc/api/runners.md | 200 |
1 files changed, 139 insertions, 61 deletions
diff --git a/doc/api/runners.md b/doc/api/runners.md index e53062ce074..3423a02c078 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -39,27 +39,38 @@ Get a list of specific runners available to the user. GET /runners GET /runners?scope=active GET /runners?type=project_type -GET /runners?status=active +GET /runners?status=online +GET /runners?paused=true 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` | -| `tag_list` | string array | no | List of the runner's tags | +| 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` and `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: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "test-1-20150125", "id": 6, "ip_address": "127.0.0.1", @@ -71,6 +82,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -86,33 +98,44 @@ Example response: ## List all runners **(FREE SELF)** Get a list of all runners in the GitLab instance (specific and shared). Access -is restricted to users with the administrator role. +is restricted to users with administrator access. ```plaintext GET /runners/all GET /runners/all?scope=online GET /runners/all?type=project_type -GET /runners/all?status=active +GET /runners/all?status=online +GET /runners/all?paused=true 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` | -| `tag_list` | string array | no | List of the runner's tags | +| 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` and `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: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "shared-runner-1", "id": 1, "ip_address": "127.0.0.1", @@ -124,6 +147,7 @@ Example response: }, { "active": true, + "paused": false, "description": "shared-runner-2", "id": 3, "ip_address": "127.0.0.1", @@ -135,6 +159,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-1-20150125", "id": 6, "ip_address": "127.0.0.1", @@ -146,6 +171,7 @@ Example response: }, { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -164,7 +190,7 @@ To view more than the first 20 runners, use [pagination](index.md#pagination). Get details of a runner. -At least the [Maintainer role](../user/permissions.md) is required to get runner details at the +At least the Maintainer role is required to get runner details at the project and group level. Instance-level runner details via this endpoint are available to all signed in users. @@ -185,11 +211,16 @@ NOTE: The `token` attribute in the response was deprecated [in GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320). and removed in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/214322). +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json { "active": true, + "paused": false, "architecture": null, "description": "test-1-20150125", "id": 6, @@ -229,16 +260,17 @@ 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 | -| `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs | -| `locked` | boolean | no | Flag indicating the runner is locked | -| `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 handles the job | +| Attribute | Type | Required | Description | +|-------------------|---------|----------|--------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a runner | +| `description` | string | no | The description of a runner | +| `active` | boolean | no | Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs | +| `paused` | boolean | no | Flag indicating whether the runner should ignore new jobs | +| `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | +| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | +| `locked` | boolean | no | Flag indicating the runner is locked | +| `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 handles the job | ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" \ @@ -249,6 +281,10 @@ NOTE: The `token` attribute in the response was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/214320) in GitLab 12.10. and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/214322) in GitLab 13.0. +NOTE: +The `active` query parameter was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json @@ -292,7 +328,12 @@ Example response: Pause a specific runner. ```plaintext -PUT --form "active=false" /runners/:runner_id +PUT --form "paused=true" /runners/:runner_id + +# --or-- + +# Deprecated: removal planned in 15.0 +PUT --form "active=false" /runners/:runner_id ``` | Attribute | Type | Required | Description | @@ -301,9 +342,19 @@ PUT --form "active=false" /runners/:runner_id ```shell curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ + --form "paused=true" "https://gitlab.example.com/api/v4/runners/6" + +# --or-- + +# Deprecated: removal planned in 15.0 +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ --form "active=false" "https://gitlab.example.com/api/v4/runners/6" ``` +NOTE: +The `active` form attribute was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + ## List runner's jobs > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) in GitLab 10.3. @@ -397,35 +448,45 @@ Example response: ## 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. +List all runners available in the project, including from ancestor groups and [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). ```plaintext 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/all?status=online +GET /projects/:id/runners/all?paused=true 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 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` | string array | no | List of the runner's tags | +| 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 show, one of: `active`, `paused`, `online` and `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: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json [ { "active": true, + "paused": false, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", @@ -437,6 +498,7 @@ Example response: }, { "active": true, + "paused": false, "description": "development_runner", "id": 5, "ip_address": "127.0.0.1", @@ -444,7 +506,7 @@ Example response: "runner_type": "instance_type", "name": null, "online": true, - "status": "paused" + "status": "online" } ] ``` @@ -504,27 +566,36 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://git ## List group's runners -List all runners (specific and shared) available in the group as well it's ancestor groups. -Shared runners are listed if at least one shared runner is defined. +List all runners available in the group as well as its ancestor groups, including [any allowed shared runners](../ci/runners/runners_scope.md#enable-shared-runners). ```plaintext GET /groups/:id/runners GET /groups/:id/runners?type=group_type -GET /groups/:id/runners?status=active +GET /groups/:id/runners/all?status=online +GET /groups/:id/runners/all?paused=true GET /groups/:id/runners?tag_list=tag1,tag2 ``` -| Attribute | Type | Required | Description | -|------------|----------------|----------|---------------------| -| `id` | integer | yes | The ID of the group owned by the authenticated user | -| `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` | string array | no | List of the runner's tags | +| Attribute | Type | Required | Description | +|------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of the group owned by the authenticated user | +| `type` | string | no | The type of runners to show, one of: `instance_type`, `group_type`, `project_type`. The `project_type` value is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351466) and will be removed in GitLab 15.0 | +| `status` | string | no | The status of runners to show, one of: `online` and `offline`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 15.0 | +| `paused` | boolean | no | Whether to include only runners that are accepting or ignoring new jobs | +| `tag_list` | string array | no | List of the runner's tags | ```shell curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners" ``` +NOTE: +The `active` and `paused` values in the `status` query parameter were deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). They are replaced by the `paused` query parameter. + +NOTE: +The `active` attribute in the response was deprecated [in GitLab 14.8](https://gitlab.com/gitlab-org/gitlab/-/issues/347211). +and will be removed in [GitLab 15.0](https://gitlab.com/gitlab-org/gitlab/-/issues/351109). It is replaced by the `paused` attribute. + Example response: ```json @@ -534,6 +605,7 @@ Example response: "description": "Shared", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": true, "runner_type": "instance_type", "name": "gitlab-runner", @@ -545,6 +617,7 @@ Example response: "description": "Test", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": true, "runner_type": "instance_type", "name": "gitlab-runner", @@ -556,6 +629,7 @@ Example response: "description": "Test 2", "ip_address": "127.0.0.1", "active": true, + "paused": false, "is_shared": false, "runner_type": "group_type", "name": "gitlab-runner", @@ -573,18 +647,20 @@ Register a new runner for the instance. POST /runners ``` -| Attribute | Type | Required | Description | -|-------------------|----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | -| `description` | string | no | Runner's description | -| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI. | -| `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` | string array | 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 handles the job | -| `maintainer_note` | string | no | Free-form maintainer notes for the runner (255 characters) | +| Attribute | Type | Required | Description | +|--------------------|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `token` | string | yes | [Registration token](#registration-and-authentication-tokens) | +| `description` | string | no | Runner's description | +| `info` | hash | no | Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin area of the UI | +| `active` | boolean | no | Deprecated: Use `:paused` instead. Whether the runner is allowed to receive jobs | +| `paused` | boolean | no | Whether the runner should ignore new jobs | +| `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` | string array | 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 handles the job | +| `maintainer_note` | string | no | [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/350730), see `maintenance_note` | +| `maintenance_note` | string | no | Free-form maintenance notes for the runner (255 characters) | ```shell curl --request POST "https://gitlab.example.com/api/v4/runners" \ @@ -603,7 +679,8 @@ Example response: ```json { "id": 12345, - "token": "6337ff461c94fd3fa32ba3b1ff4125" + "token": "6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" } ``` @@ -743,6 +820,7 @@ Example response: ```json { - "token": "6337ff461c94fd3fa32ba3b1ff4125" + "token": "6337ff461c94fd3fa32ba3b1ff4125", + "token_expires_at": "2021-09-27T21:05:03.203Z" } ``` |