这是此页面的过期版本。你可以查看最新版本或浏览历史。

Runners API

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

Runners API
Runners API

Runners API

在 GitLab 8.5 中引入

Registration and authentication tokens

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

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

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

您使用注册令牌通过 GitLab API 注册了 Runner，并返回了身份验证令牌.
您使用该身份验证令牌并将其添加到Runner 的配置文件中：
```
[[runners]]
  token = "<authentication_token>" 
```

然后将 GitLab 和 Runner 连接起来.

List owned runners

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

GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=active
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_type` ， `group_type` ， `project_type`
`status`	string	no	要显示的跑步者状态，其中之一： `active` ， `paused` ， `online` ， `offline`
`tag_list`	字符串数组	no	跑步者标签列表

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

响应示例：

[  {  "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权限的用户.

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

Attribute	Type	Required	Description
`scope`	string	no	不推荐使用：改为使用`type`或`status` . 参与者显示的范围，其中之一： `specific` ， `shared` ， `active` ，已`paused` ， `online` ， `offline` ；显示所有跑步者（如果未提供）
`type`	string	no	要显示的跑步者的类型，其中之一： `instance_type` ， `group_type` ， `project_type`
`status`	string	no	要显示的跑步者状态，其中之一： `active` ， `paused` ， `online` ， `offline`
`tag_list`	字符串数组	no	跑步者标签列表

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

响应示例：

[  {  "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 /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	跑步者 ID

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

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

响应示例：

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

更新跑步者的详细信息.

PUT /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	跑步者 ID
`description`	string	no	跑步者
`active`	boolean	no	跑步者的状态；可以设置为`true`或`false`
`tag_list`	array	no	跑步者的标签列表；放置标签数组，这些标签应最终分配给跑步者
`run_untagged`	boolean	no	指示跑步者可以执行未加标签的作业的标志
`locked`	boolean	no	指示跑步者被锁定的标志
`access_level`	string	no	跑步者的 access_level; `not_protected`或`ref_protected`
`maximum_timeout`	integer	no	此 Runner 处理作业的最大超时时间

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 中删除.

响应示例：

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

卸下流道.

DELETE /runners/:id

Attribute	Type	Required	Description
`id`	integer	yes	The 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

在 GitLab 10.3 中引入 .

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

GET /runners/:id/jobs

Attribute	Type	Required	Description
`id`	integer	yes	跑步者 ID
`status`	string	no	工作状态；其中之一： `running` ， `success` ， `failed` ， `canceled`
`order_by`	string	no	按`id`订购工作.
`sort`	string	no	按`asc`或`desc`顺序对作业进行排序（默认值： `desc` ）

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"

响应示例：

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

Attribute	Type	Required	Description
`id`	integer/string	yes	经过身份验证的用户拥有的项目的 ID 或URL 编码路径
`scope`	string	no	不推荐使用：改为使用`type`或`status` . 要显示的特定跑步者的范围，其中之一： `active` ， `paused` ， `online` ， `offline` ；显示所有跑步者（如果未提供）
`type`	string	no	要显示的跑步者的类型，其中之一： `instance_type` ， `group_type` ， `project_type`
`status`	string	no	要显示的跑步者状态，其中之一： `active` ， `paused` ， `online` ， `offline`
`tag_list`	字符串数组	no	跑步者标签列表

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

响应示例：

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

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

POST /projects/:id/runners

Attribute	Type	Required	Description
`id`	integer/string	yes	经过身份验证的用户拥有的项目的 ID 或URL 编码路径
`runner_id`	integer	yes	跑步者 ID

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

响应示例：

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

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

DELETE /projects/:id/runners/:runner_id

Attribute	Type	Required	Description
`id`	integer/string	yes	经过身份验证的用户拥有的项目的 ID 或URL 编码路径
`runner_id`	integer	yes	跑步者 ID

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

List group’s runners

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

GET /groups/:id/runners
GET /groups/:id/runners?type=group_type
GET /groups/:id/runners?status=active
GET /groups/:id/runners?tag_list=tag1,tag2

Attribute	Type	Required	Description
`id`	integer	yes	认证用户拥有的组的 ID
`type`	string	no	要显示的跑步者的类型，其中之一： `instance_type` ， `group_type` ， `project_type`
`status`	string	no	要显示的跑步者状态，其中之一： `active` ， `paused` ， `online` ， `offline`
`tag_list`	字符串数组	no	跑步者标签列表

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

响应示例：

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

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

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_protected`或`ref_protected`
`maximum_timeout`	integer	no	此 Runner 处理作业的最大超时时间

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	跑步者已创建

响应示例：

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

Delete a registered 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=<authentication_token>"

Response:

Status	Description
204	跑步者已被删除

Verify authentication 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	凭证有效
403	凭证无效

GitCode / 帮助文档

runners

Runners API

Runners API

Registration and authentication tokens

List owned runners

List all runners

Get runner’s details

Update runner’s details

Remove 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 registered Runner

Verify authentication for a registered Runner