kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/runners.md
Steve Azzopardi 9aedc05e02
Fix documentation for list runners 
We are specifying that we will only return the shared runners on two
condition; 1 if project has any available 2 if shared runners are
enabled.

2 is not correct. In the admin UI, when the user press "disable shared
runners" we still show the runners to show what kind of runners are
available when the user enables them. We want the API to mimic this
behavior from the UI.

closes https://gitlab.com/gitlab-org/gitlab-ce/issues/52918
2018-10-19 12:20:06 +02:00

15 KiB
Raw Blame History

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
GET /runners?type=project_type
GET /runners?status=active
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 
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,
        "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
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 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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: 9koXpg98eAheJpvBs5tK" "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-ce",
            "path_with_namespace": "gitlab-org/gitlab-ce"
        }
    ],
    "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
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: 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,
    "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-ce",
            "path_with_namespace": "gitlab-org/gitlab-ce"
        }
    ],
    "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
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 runner's jobs

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 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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
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 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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: 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,
    "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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners/9"

Register a new Runner

Register a new Runner for the instance.

POST /runners
Attribute Type Required Description
token string yes Registration token (Read how to obtain a 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 Array[String] no List of Runner's tags
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=ipzXrMhuyyJPifUt6ANz" --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 registed 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=ebb6fc00521627750c8bb750f2490e"

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=ebb6fc00521627750c8bb750f2490e"

Response:

Status Description
200 Credentials are valid
403 Credentials are invalid