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.

TokenDescription
Registration tokenToken used to register the Runner. It can be obtained through GitLab.
Authentication tokenToken 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 Runners API.

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 authentication token is returned.
  2. You use that authentication token and add it to the Runner’s configuration file:

    [[runners]]
      token = "<authentication_token>"
    

GitLab and 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
AttributeTypeRequiredDescription
scopestringnoDeprecated: Use type or status instead. The scope of specific runners to show, one of: active, paused, online, offline; showing all runners if none provided
typestringnoThe type of runners to show, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to show, one of: active, paused, online, offline
tag_liststring arraynoList of 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
AttributeTypeRequiredDescription
scopestringnoDeprecated: 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
typestringnoThe type of runners to show, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to show, one of: active, paused, online, offline
tag_liststring arraynoList of 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
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

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"
        }
    ],
    "token": "205086a8e3b9a2b818ffac9b89d102",
    "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
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
descriptionstringnoThe description of a runner
activebooleannoThe state of a runner; can be set to true or false
tag_listarraynoThe list of tags for a runner; put array of tags, that should be finally assigned to a runner
run_untaggedbooleannoFlag indicating the runner can execute untagged jobs
lockedbooleannoFlag indicating the runner is locked
access_levelstringnoThe access_level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum 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"

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"
        }
    ],
    "token": "205086a8e3b9a2b818ffac9b89d102",
    "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
AttributeTypeRequiredDescription
idintegeryesThe 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
AttributeTypeRequiredDescription
idintegeryesThe ID of a runner
statusstringnoStatus of the job; one of: running, success, failed, canceled
order_bystringnoOrder jobs by id.
sortstringnoSort 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
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
scopestringnoDeprecated: Use type or status instead. The scope of specific runners to show, one of: active, paused, online, offline; showing all runners if none provided
typestringnoThe type of runners to show, one of: instance_type, group_type, project_type
statusstringnoThe status of runners to show, one of: active, paused, online, offline
tag_liststring arraynoList of 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
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
runner_idintegeryesThe 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
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
runner_idintegeryesThe ID of a runner
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

Register a new Runner

Register a new Runner for the instance.

POST /runners
AttributeTypeRequiredDescription
tokenstringyesRegistration token.
descriptionstringnoRunner’s description
infohashnoRunner’s metadata
activebooleannoWhether the Runner is active
lockedbooleannoWhether the Runner should be locked for current project
run_untaggedbooleannoWhether the Runner should handle untagged jobs
tag_liststring arraynoList of Runner’s tags
access_levelstringnoThe access_level of the runner; not_protected or ref_protected
maximum_timeoutintegernoMaximum 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:

StatusDescription
201Runner was created

Example response:

{
    "id": "12345",
    "token": "6337ff461c94fd3fa32ba3b1ff4125"
}

Delete a registered Runner

Deletes a registered Runner.

DELETE /runners
AttributeTypeRequiredDescription
tokenstringyesRunner’s authentication token.
curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>"

Response:

StatusDescription
204Runner was deleted

Verify authentication for a registered Runner

Validates authentication credentials for a registered Runner.

POST /runners/verify
AttributeTypeRequiredDescription
tokenstringyesRunner’s authentication token.
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>"

Response:

StatusDescription
200Credentials are valid
403Credentials are invalid