Welcome to mirror list, hosted at ThFree Co, Russian Federation.

gitlab.com/gitlab-org/gitlab-foss.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
path: root/doc/api/runners.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/runners.md')
-rw-r--r--doc/api/runners.md55
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.
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-15 23:40:44 +0300