Registering a runner with a registration token is deprecated and disabled by default in GitLab 17.0 and later.
Use this API to register a runner with an instance, verify its authentication, reset its authentication token, and unregister it. GitLab Runner uses these endpoints itself.
To create a runner, or to manage runners that already exist, use the Runners endpoints.
Create a runner
POST /api/v4/runners
Creates a runner.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
access_ | String | Access level of the runner Allowed values: not_,ref_ |
active | Boolean | If true,paused instead.paused |
description | String | Description of the runner |
info | Object | Runner’s metadata |
info. | String | Runner’s architecture |
info. | String | Runner’s name |
info. | String | Runner’s platform |
info. | String | Runner’s revision |
info. | String | Runner’s version |
locked | Boolean | If true, |
maintainer_ | String | Free-maintenance_ instead.maintenance_ |
maintenance_ | String | Free-maintainer_ |
maximum_ | Integer | Maximum time, |
paused | Boolean | If true,active |
run_ | Boolean | If true, |
tag_ | Array of strings | List of runner tags |
tokenRequired | String | Registration token |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
410 | Gone | — |
Delete a registered runner
DELETE /api/v4/runners
Deletes a specified registered runner.
Parameters
| Name | Type | Description |
|---|---|---|
tokenQuery, | String | Authentication token of the runner |
Responses
| Code | Description | Schema |
|---|---|---|
204 | Resource deleted | — |
400 | Bad Request | — |
403 | Forbidden | — |
Delete a registered runner manager
DELETE /api/v4/runners/managers
Parameters
| Name | Type | Description |
|---|---|---|
tokenQuery, | String | Authentication token of the runner |
system_Query, | String | System identifier of the runner |
Responses
| Code | Description | Schema |
|---|---|---|
204 | Runner manager was deleted | — |
400 | Bad Request | — |
403 | Forbidden | — |
404 | Not Found | — |
Reset a runner authentication token with the current token
POST /api/v4/runners/reset_authentication_token
Resets a runner authentication token with the token used to authenticate the request.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
tokenRequired | String | Authentication token of the runner |
Responses
| Code | Description | Schema |
|---|---|---|
201 | Created | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
422 | Unprocessable Entity | — |
Discover Job Router information
GET /api/v4/runners/router/discovery
Discovers Job Router information for a runner. You must provide a valid runner authentication token.
Responses
| Code | Description | Schema |
|---|---|---|
200 | OK | APIEntities |
403 | 403 Forbidden | — |
501 | 501 Not Implemented | — |
Verify authentication for a registered runner
POST /api/v4/runners/verify
Verifies authentication for a registered runner.
Request body (application/json)
| Property | Type | Description |
|---|---|---|
system_ | String | System identifier of the runner.token starts with glrt- |
tokenRequired | String | Authentication token of the runner |
Responses
| Code | Description | Schema |
|---|---|---|
200 | Credentials are valid | APIEntities |
400 | Bad Request | — |
403 | Forbidden | — |
422 | Runner is orphaned | — |
Schemas
Objects returned by the operations above and objects nested in their request bodies.
APIEntitiesCiJobRouterDiscoveryInformation
| Property | Type | Description |
|---|---|---|
server_ | String | Example:wss: |
APIEntitiesCiResetTokenResult
| Property | Type | Description |
|---|---|---|
token | String | — |
token_ | String | — |
APIEntitiesCiRunnerRegistrationDetails
| Property | Type | Description |
|---|---|---|
id | String | — |
token | String | — |
token_ | String | — |