Runners API

原文:https://docs.gitlab.com/ee/api/runners.html

Runners API

在 GitLab 8.5 中引入

Registration and authentication tokens

将 Runner 与 GitLab 连接时要考虑两个标记.

Token Description
注册令牌 用于注册 Runner 的令牌. 可以通过 GitLab 获得 .
认证令牌 用于通过 GitLab 实例对 Runner 进行身份验证的令牌. 它可以在注册 Runner时自动获得,也可以通过 Runners API手动注册时获得 .

这是在 Runner 注册中如何使用两个令牌的示例:

  1. 您使用注册令牌通过 GitLab API 注册了 Runner,并返回了身份验证令牌.
  2. 您使用该身份验证令牌并将其添加到Runner 的配置文件中

    1. [[runners]]
    2. token = "<authentication_token>"

然后将 GitLab 和 Runner 连接起来.

List owned runners

获取可供用户使用的特定跑步者的列表.

  1. GET /runners
  2. GET /runners?scope=active
  3. GET /runners?type=project_type
  4. GET /runners?status=active
  5. 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 要显示的跑步者的类型,其中之一: instance_typegroup_typeproject_type
status string no 要显示的跑步者状态,其中之一: activepausedonlineoffline
tag_list 字符串数组 no 跑步者标签列表
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"

响应示例:

  1. [ { "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

获取 GitLab 实例中所有跑步者的列表(特定的和共享的). 访问仅限于具有admin权限的用户.

  1. GET /runners/all
  2. GET /runners/all?scope=online
  3. GET /runners/all?type=project_type
  4. GET /runners/all?status=active
  5. GET /runners/all?tag_list=tag1,tag2
Attribute Type Required Description
scope string no 不推荐使用:改为使用typestatus . 参与者显示的范围,其中之一: specificsharedactive ,已pausedonlineoffline ; 显示所有跑步者(如果未提供)
type string no 要显示的跑步者的类型,其中之一: instance_typegroup_typeproject_type
status string no 要显示的跑步者状态,其中之一: activepausedonlineoffline
tag_list 字符串数组 no 跑步者标签列表
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"

响应示例:

  1. [ { "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

获取跑步者的详细信息.

  1. GET /runners/:id
Attribute Type Required Description
id integer yes 跑步者 ID
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

注意:响应中的token属性在 GitLab 12.10中已弃用. 并在GitLab 13.0 中删除.

响应示例:

  1. { "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

更新跑步者的详细信息.

  1. PUT /runners/:id
Attribute Type Required Description
id integer yes 跑步者 ID
description string no 跑步者
active boolean no 跑步者的状态; 可以设置为truefalse
tag_list array no 跑步者的标签列表; 放置标签数组,这些标签应最终分配给跑步者
run_untagged boolean no 指示跑步者可以执行未加标签的作业的标志
locked boolean no 指示跑步者被锁定的标志
access_level string no 跑步者的 access_level; not_protectedref_protected
maximum_timeout integer no 此 Runner 处理作业的最大超时时间
  1. 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"

注意:响应中的token属性在 GitLab 12.10中已弃用. 并在GitLab 13.0 中删除.

响应示例:

  1. { "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

卸下流道.

  1. DELETE /runners/:id
Attribute Type Required Description
id integer yes The ID of a runner
  1. curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

List runner’s jobs

在 GitLab 10.3 中引入 .

列出正在处理或由指定运行程序处理的作业.

  1. GET /runners/:id/jobs
Attribute Type Required Description
id integer yes 跑步者 ID
status string no 工作状态; 其中之一: runningsuccessfailedcanceled
order_by string no id订购工作.
sort string no ascdesc顺序对作业进行排序(默认值: desc
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

响应示例:

  1. [ { "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. 如果定义了至少一个共享运行程序,则列出共享运行程序.

  1. GET /projects/:id/runners
  2. GET /projects/:id/runners?scope=active
  3. GET /projects/:id/runners?type=project_type
  4. GET /projects/:id/runners?status=active
  5. GET /projects/:id/runners?tag_list=tag1,tag2
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或URL 编码路径
scope string no 不推荐使用:改为使用typestatus . 要显示的特定跑步者的范围,其中之一: activepausedonlineoffline ; 显示所有跑步者(如果未提供)
type string no 要显示的跑步者的类型,其中之一: instance_typegroup_typeproject_type
status string no 要显示的跑步者状态,其中之一: activepausedonlineoffline
tag_list 字符串数组 no 跑步者标签列表
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"

响应示例:

  1. [ { "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

在项目中启用可用的特定运行器.

  1. POST /projects/:id/runners
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或URL 编码路径
runner_id integer yes 跑步者 ID
  1. curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9"

响应示例:

  1. { "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

禁用项目中的特定运行器. 仅当该项目不是与指定运行器关联的唯一项目时,它才有效. 如果是这样,则返回错误. 改用” 删除亚军”电话.

  1. DELETE /projects/:id/runners/:runner_id
Attribute Type Required Description
id integer/string yes 经过身份验证的用户拥有的项目的 ID 或URL 编码路径
runner_id integer yes 跑步者 ID
  1. curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"

List group’s runners

列出组中的所有跑步者(特定的和共享的)以及其祖先组. 如果定义了至少一个共享运行程序,则列出共享运行程序.

  1. GET /groups/:id/runners
  2. GET /groups/:id/runners?type=group_type
  3. GET /groups/:id/runners?status=active
  4. GET /groups/:id/runners?tag_list=tag1,tag2
Attribute Type Required Description
id integer yes 认证用户拥有的组的 ID
type string no 要显示的跑步者的类型,其中之一: instance_typegroup_typeproject_type
status string no 要显示的跑步者状态,其中之一: activepausedonlineoffline
tag_list 字符串数组 no 跑步者标签列表
  1. curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"

响应示例:

  1. [ { "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

为该实例注册一个新的运行器.

  1. POST /runners
Attribute Type Required Description
token string yes Registration token.
description string no 跑步者的描述
info hash no 跑步者的元数据
active boolean no 跑步者是否活跃
locked boolean no Runner 是否应该为当前项目锁定
run_untagged boolean no 跑步者是否应处理未加标签的工作
tag_list 字符串数组 no 跑步者标签列表
access_level string no 跑步者的 access_level; not_protectedref_protected
maximum_timeout integer no 此 Runner 处理作业的最大超时时间
  1. 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 跑步者已创建

响应示例:

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

Delete a registered Runner

删除注册的跑步者.

  1. DELETE /runners
Attribute Type Required Description
token string yes Runner’s authentication token.
  1. curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>"

Response:

Status Description
204 跑步者已被删除

Verify authentication for a registered Runner

验证注册的运行程序的身份验证凭据.

  1. POST /runners/verify
Attribute Type Required Description
token string yes Runner’s authentication token.
  1. curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>"

Response:

Status Description
200 凭证有效
403 凭证无效