Pirate Praveen dd76d996b0 New upstream version 15.1.3+ds1

2022-07-23 20:15:48 +02:00

34 KiB

Raw Blame History

stage	group	info
Verify	Runner	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Runners API (FREE)

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 automatically when you register a runner or by the Runner API when you manually register a runner or reset the authentication token.

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=online
GET /runners?paused=true
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` and `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: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`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"

NOTE: The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.

NOTE: The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

List all runners (FREE SELF)

Get a list of all runners in the GitLab instance (specific and shared). Access is restricted to users with administrator access.

GET /runners/all
GET /runners/all?scope=online
GET /runners/all?type=project_type
GET /runners/all?status=online
GET /runners/all?paused=true
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` and `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: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`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"

NOTE: The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.

NOTE: The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    },
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-2",
        "id": 3,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": true,
        "status": "paused"
    },
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

To view more than the first 20 runners, use pagination.

Get runner's details

Get details of a runner.

At least the Maintainer role is required to get runner details at the project and group level.

Instance-level runner details via this endpoint are available to all signed in users.

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: The token attribute in the response was deprecated in GitLab 12.10. and removed in GitLab 13.0.

NOTE: The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "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	Deprecated: Use `:paused` instead. Flag indicating whether the runner is allowed to receive jobs
`paused`	boolean	no	Flag indicating whether the runner should ignore new jobs
`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 handles 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: The token attribute in the response was deprecated in GitLab 12.10. and removed in GitLab 13.0.

NOTE: The active query parameter was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "group_type",
    "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
}

Pause a runner

Pause a specific runner.

PUT --form "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 16.0
PUT --form "active=false" /runners/:runner_id

Attribute	Type	Required	Description
`runner_id`	integer	yes	The ID of a runner

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "paused=true"  "https://gitlab.example.com/api/v4/runners/6"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"

NOTE: The active form attribute was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

List runner's jobs

Introduced in GitLab 10.3.

List jobs that are being processed or were processed by the specified runner. The list of jobs is limited to projects where the user has at least the Reporter role.

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`). Specify `order_by` as well, including for `id`.

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 available in the project, including from ancestor groups and any allowed shared runners.

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners/all?status=online
GET /projects/:id/runners/all?paused=true
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` and `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: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`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"

NOTE: The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.

NOTE: The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    }
]

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,
    "runner_type": "project_type",
    "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 call to delete a runner 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 available in the group as well as its ancestor groups, including any allowed shared runners.

GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners/all?status=online
GET /groups/:id/runners/all?paused=true
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`. The `project_type` value is deprecated and will be removed in GitLab 15.0
`status`	string	no	The status of runners to show, one of: `online`, `offline`, `stale`, and `never_contacted`. `active` and `paused` are also possible values which were deprecated in GitLab 14.8 and will be removed in GitLab 16.0
`paused`	boolean	no	Whether to include only runners that are accepting or ignoring new jobs
`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"

NOTE: The active and paused values in the status query parameter were deprecated in GitLab 14.8. and will be removed in GitLab 16.0. They are replaced by the paused query parameter.

NOTE: The active attribute in the response was deprecated in GitLab 14.8. and will be removed in GitLab 16.0. It is replaced by the paused attribute.

Example response:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  },
  {
    "id": 6,
    "description": "Test",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": true,
    "runner_type": "instance_type",
    "name": "gitlab-runner",
    "online": false,
    "status": "offline"
  },
  {
    "id": 8,
    "description": "Test 2",
    "ip_address": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  }
]

Register a new runner

POST /runners

Attribute	Type	Required	Description
`token`	string	yes	Registration token
`description`	string	no	Runner's description
`info`	hash	no	Runner's metadata. You can include `name`, `version`, `revision`, `platform`, and `architecture`, but only `version` is displayed in the Admin Area of the UI
`active`	boolean	no	Deprecated: Use `:paused` instead. Whether the runner is allowed to receive jobs
`paused`	boolean	no	Whether the runner should ignore new jobs
`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 handles the job
`maintainer_note`	string	no	Deprecated, see `maintenance_note`
`maintenance_note`	string	no	Free-form maintenance notes for the runner (1024 characters)

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",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Delete a runner

There are two ways to delete a runner:

By specifying the runner ID.
By specifying the runner's authentication token.

Delete a runner by ID

To delete the runner by ID, use your access token with the runner's ID:

DELETE /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner. The ID is visible in the UI under Settings > CI/CD. Expand Runners, and below the Remove Runner button is an ID preceded by the pound sign, for example, `#6`.

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

Delete a runner by authentication token

To delete the runner by using its authentication token:

DELETE /runners

Attribute	Type	Required	Description
`token`	string	yes	The 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

Reset instance's runner registration token

Introduced in GitLab 14.3.

Resets the runner registration token for the GitLab instance.

POST /runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/reset_registration_token"

Reset project's runner registration token

Introduced in GitLab 14.3.

Resets the runner registration token for a project.

POST /projects/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"

Reset group's runner registration token

Introduced in GitLab 14.3.

Resets the runner registration token for a group.

POST /groups/:id/runners/reset_registration_token

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

Reset runner's authentication token by using the runner ID

Resets the runner's authentication token by using its runner ID.

POST /runners/:id/reset_authentication_token

Attribute	Type	Required	Description
`id`	integer	yes	The ID of a runner

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

Reset runner's authentication token by using the current token

Resets the runner's authentication token by using the current token's value as an input.

POST /runners/reset_authentication_token

Attribute	Type	Required	Description
`token`	string	yes	The current token of the runner

curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

Example response:

{
    "token": "6337ff461c94fd3fa32ba3b1ff4125",
    "token_expires_at": "2021-09-27T21:05:03.203Z"
}

34 KiB Raw Blame History

Runners API (FREE)

Registration and authentication tokens

List owned runners

List all runners (FREE SELF)

Get runner's details

Update runner's details

Pause a runner

List runner's jobs

List project's runners

Enable a runner in project

Disable a runner from project

List group's runners

Register a new runner

Delete a runner

Delete a runner by ID

Delete a runner by authentication token

Verify authentication for a registered runner

Reset instance's runner registration token

Reset project's runner registration token

Reset group's runner registration token

Reset runner's authentication token by using the runner ID

Reset runner's authentication token by using the current token

34 KiB

Raw Blame History