@@ -6,30 +6,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
...
@@ -6,30 +6,30 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Runners API
# Runners API
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) in GitLab 8.5.
## Registration and authentication tokens
## Registration and authentication tokens
There are two tokens to take into account when connecting a Runner with GitLab.
There are two tokens to take into account when connecting a runner with GitLab.
| Token | Description |
| 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). |
| 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). |
| 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 Runner API](#register-a-new-runner). |
Here's an example of how the two tokens are used in Runner registration:
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
1. You register the runner via the GitLab API using a registration token, and an
authentication token is returned.
authentication token is returned.
1. You use that authentication token and add it to the
1. You use that authentication token and add it to the
| `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs |
| `run_untagged`| boolean | no | Flag indicating the runner can execute untagged jobs |
| `locked` | boolean | no | Flag indicating the runner is locked |
| `locked` | boolean | no | Flag indicating the runner is locked |
| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` |
| `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 |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job |
```shell
```shell
curl --request PUT --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/runners/6"--form"description=test-1-20150125-test"--form"tag_list=ruby,mysql,tag1,tag2"
curl --request PUT --header"PRIVATE-TOKEN: <your_access_token>""https://gitlab.example.com/api/v4/runners/6"--form"description=test-1-20150125-test"--form"tag_list=ruby,mysql,tag1,tag2"
| `description`| string | no | Runner's description|
| `description`| string | no | Runner's description|
| `info` | hash | no | Runner's metadata |
| `info` | hash | no | Runner's metadata |
| `active` | boolean | no | Whether the Runner is active |
| `active` | boolean | no | Whether the runner is active |
| `locked` | boolean | no | Whether the Runner should be locked for current project |
| `locked` | boolean | no | Whether the runner should be locked for current project |
| `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs |
| `run_untagged` | boolean | no | Whether the runner should handle untagged jobs |
| `tag_list` | string array | no | List of Runner's tags |
| `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` |
| `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 |
| `maximum_timeout` | integer | no | Maximum timeout set when this runner will handle the job |
```shell
```shell
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"
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"
...
@@ -580,9 +580,9 @@ Example response:
...
@@ -580,9 +580,9 @@ Example response:
}
}
```
```
## Delete a registered Runner
## Delete a registered runner
Deletes a registered Runner.
Deletes a registered runner.
```plaintext
```plaintext
DELETE /runners
DELETE /runners
...
@@ -602,9 +602,9 @@ Response:
...
@@ -602,9 +602,9 @@ Response:
|-----------|---------------------------------|
|-----------|---------------------------------|
| 204 | Runner was deleted |
| 204 | Runner was deleted |
## Verify authentication for a registered Runner
## Verify authentication for a registered runner
Validates authentication credentials for a registered Runner.
Validates authentication credentials for a registered runner.
@@ -329,7 +329,7 @@ are listed in the descriptions of the relevant settings.
...
@@ -329,7 +329,7 @@ are listed in the descriptions of the relevant settings.
| `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. |
| `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. |
| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes |
| `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes |
| `shared_runners_enabled` | boolean | no | (**If enabled, requires:**`shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. |
| `shared_runners_enabled` | boolean | no | (**If enabled, requires:**`shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. |
| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. |
| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **(PREMIUM)** Set the maximum number of pipeline minutes that a group can use on shared runners per month. |
| `sign_in_text` | string | no | Text on the login page. |
| `sign_in_text` | string | no | Text on the login page. |
| `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. |
| `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. |