Runners API
Introduced in GitLab 8.5
List owned runners
Get a list of specific runners available to the user.
GET /runners
GET /runners?scope=active
Attribute | Type | Required | Description |
---|---|---|---|
scope |
string | no | The scope of specific runners to show, one of: active , paused , online ; showing all runners if none provided |
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners"
Example response:
[
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
"name": null
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
"name": null
}
]
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
Attribute | Type | Required | Description |
---|---|---|---|
scope |
string | no | The scope of runners to show, one of: specific , shared , active , paused , online ; showing all runners if none provided |
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/all"
Example response:
[
{
"active": true,
"description": "shared-runner-1",
"id": 1,
"is_shared": true,
"name": null
},
{
"active": true,
"description": "shared-runner-2",
"id": 3,
"is_shared": true,
"name": null
},
{
"active": true,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
"name": null
},
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
"name": null
}
]
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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6"
Example response:
{
"active": true,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
"is_shared": false,
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
"path": "gitlab-ce",
"path_with_namespace": "gitlab-org/gitlab-ce"
}
],
"token": "205086a8e3b9a2b818ffac9b89d102",
"revision": null,
"tag_list": [
"ruby",
"mysql"
],
"version": null,
"access_level": "ref_protected"
}
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
|
curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
Example response:
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"is_shared": false,
"contacted_at": "2016-01-25T16:39:48.066Z",
"name": null,
"platform": null,
"projects": [
{
"id": 1,
"name": "GitLab Community Edition",
"name_with_namespace": "GitLab.org / GitLab Community Edition",
"path": "gitlab-ce",
"path_with_namespace": "gitlab-org/gitlab-ce"
}
],
"token": "205086a8e3b9a2b818ffac9b89d102",
"revision": null,
"tag_list": [
"ruby",
"mysql",
"tag1",
"tag2"
],
"version": null,
"access_level": "ref_protected"
}
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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6"
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 and shared runners usage is enabled in the project's settings.
GET /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 |
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners"
Example response:
[
{
"active": true,
"description": "test-2-20150125",
"id": 8,
"is_shared": false,
"name": null
},
{
"active": true,
"description": "development_runner",
"id": 5,
"is_shared": true,
"name": null
}
]
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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9"
Example response:
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"is_shared": false,
"name": null
}
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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9"