Runners API
Introduced in GitLab 8.5.
Registration and authentication tokens
There are two tokens to take into account when connecting a runner with GitLab.
Token | Description |
---|---|
Registration token | Token used to register the runner. It can be obtained through GitLab. |
Authentication token | Token used to authenticate the runner with the GitLab instance. It is obtained either automatically when registering a runner, or manually when registering the runner via the Runner API. |
Here's an example of how the two tokens are used in runner registration:
-
You register the runner via the GitLab API using a registration token, and an authentication token is returned.
-
You use that authentication token and add it to the runner's configuration file:
[[runners]] token = "<authentication_token>"
GitLab and the runner are then connected.
List owned runners
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?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 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
Example response:
[
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
"ip_address": "127.0.0.1",
"name": null,
"online": true,
"status": "online"
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
"is_shared": false,
"name": null,
"online": false,
"status": "offline"
}
]
List all runners
Get a list of all runners in the GitLab instance (specific and shared). Access
is restricted to users with admin
privileges.
GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=active
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 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
Example response:
[
{
"active": true,
"description": "shared-runner-1",
"id": 1,
"ip_address": "127.0.0.1",
"is_shared": true,
"name": null,
"online": true,
"status": "online"
},
{
"active": true,
"description": "shared-runner-2",
"id": 3,
"ip_address": "127.0.0.1",
"is_shared": true,
"name": null,
"online": false
"status": "offline"
},
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"ip_address": "127.0.0.1",
"is_shared": false,
"name": null,
"online": true
"status": "paused"
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
"is_shared": false,
"name": null,
"online": false,
"status": "offline"
}
]
Get runner's details
Get details of a runner.
GET /runners/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of a runner |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
NOTE: Note:
The token
attribute in the response was deprecated in GitLab 12.10.
and removed in GitLab 13.0.
Example response:
{
"active": true,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
"ip_address": "127.0.0.1",
"is_shared": false,
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
"online": true,
"status": "online",
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
}
],
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
"version": null,
"access_level": "ref_protected",
"maximum_timeout": 3600
}
Update runner's details
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 will handle the job |
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"
NOTE: Note:
The token
attribute in the response was deprecated in GitLab 12.10.
and removed in GitLab 13.0.
Example response:
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"ip_address": "127.0.0.1",
"is_shared": false,
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
"online": true,
"status": "online",
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
"path": "gitlab-foss",
"path_with_namespace": "gitlab-org/gitlab-foss"
}
],
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
"version": null,
"access_level": "ref_protected",
"maximum_timeout": null
}
Remove a runner
Remove a runner.
DELETE /runners/:id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of a runner |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
List runner's jobs
Introduced in GitLab 10.3.
List jobs that are being processed or were processed by specified runner.
GET /runners/:id/jobs
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer | yes | The ID of a runner |
status |
string | no | Status of the job; one of: running , success , failed , canceled
|
order_by |
string | no | Order jobs by id . |
sort |
string | no | Sort jobs in asc or desc order (default: desc ) |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
Example response:
[
{
"id": 2,
"ip_address": "127.0.0.1",
"status": "running",
"stage": "test",
"name": "test",
"ref": "master",
"tag": false,
"coverage": null,
"created_at": "2017-11-16T08:50:29.000Z",
"started_at": "2017-11-16T08:51:29.000Z",
"finished_at": "2017-11-16T08:53:29.000Z",
"duration": 120,
"user": {
"id": 1,
"name": "John Doe2",
"username": "user2",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
"web_url": "http://localhost/user2",
"created_at": "2017-11-16T18:38:46.000Z",
"bio": null,
"location": null,
"public_email": "",
"skype": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": null
},
"commit": {
"id": "97de212e80737a608d939f648d959671fb0a0142",
"short_id": "97de212e",
"title": "Update configuration\r",
"created_at": "2017-11-16T08:50:28.000Z",
"parent_ids": [
"1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
"498214de67004b1da3d820901307bed2a68a8ef6"
],
"message": "See merge request !123",
"author_name": "John Doe2",
"author_email": "user2@example.org",
"authored_date": "2017-11-16T08:50:27.000Z",
"committer_name": "John Doe2",
"committer_email": "user2@example.org",
"committed_date": "2017-11-16T08:50:27.000Z"
},
"pipeline": {
"id": 2,
"sha": "97de212e80737a608d939f648d959671fb0a0142",
"ref": "master",
"status": "running"
},
"project": {
"id": 1,
"description": null,
"name": "project1",
"name_with_namespace": "John Doe2 / project1",
"path": "project1",
"path_with_namespace": "namespace1/project1",
"created_at": "2017-11-16T18:38:46.620Z"
}
}
]
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.
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?tag_list=tag1,tag2
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project 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 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
Example response:
[
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"ip_address": "127.0.0.1",
"is_shared": false,
"name": null,
"online": false,
"status": "offline"
},
{
"active": true,
"description": "development_runner",
"id": 5,
"ip_address": "127.0.0.1",
"is_shared": true,
"name": null,
"online": true
"status": "paused"
}
]
Enable a runner in project
Enable an available specific runner in the project.
POST /projects/:id/runners
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
runner_id |
integer | yes | The ID of a runner |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9"
Example response:
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"ip_address": "127.0.0.1",
"is_shared": false,
"name": null,
"online": true,
"status": "online"
}
Disable a runner from project
Disable a specific 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 Remove a runner call instead.
DELETE /projects/:id/runners/:runner_id
Attribute | Type | Required | Description |
---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
runner_id |
integer | yes | The ID of a runner |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"
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.
GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners?status=active
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 |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
Example response:
[
{
"id": 3,
"description": "Shared",
"ip_address": "127.0.0.1",
"active": true,
"is_shared": true,
"name": "gitlab-runner",
"online": null,
"status": "not_connected"
},
{
"id": 6,
"description": "Test",
"ip_address": "127.0.0.1",
"active": true,
"is_shared": true,
"name": "gitlab-runner",
"online": false,
"status": "offline"
},
{
"id": 8,
"description": "Test 2",
"ip_address": "127.0.0.1",
"active": true,
"is_shared": false,
"name": "gitlab-runner",
"online": null,
"status": "not_connected"
}
]
Register a new runner
Register a new runner for the instance.
POST /runners
Attribute | Type | Required | Description |
---|---|---|---|
token |
string | yes | Registration token. |
description |
string | no | Runner's description |
info |
hash | no | Runner's metadata |
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 will handle the job |
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"
Response:
Status | Description |
---|---|
201 | Runner was created |
Example response:
{
"id": "12345",
"token": "6337ff461c94fd3fa32ba3b1ff4125"
}
Delete a registered runner
Deletes a registered runner.
DELETE /runners
Attribute | Type | Required | Description |
---|---|---|---|
token |
string | yes | Runner's authentication token. |
curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>"
Response:
Status | Description |
---|---|
204 | Runner was deleted |
Verify authentication for a registered runner
Validates authentication credentials for a registered runner.
POST /runners/verify
Attribute | Type | Required | Description |
---|---|---|---|
token |
string | yes | Runner's authentication token. |
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>"
Response:
Status | Description |
---|---|
200 | Credentials are valid |
403 | Credentials are invalid |