Skip to content

帮助文档
帮助文档

GitCode / 帮助文档

通知 1778
Star 578
Fork 457
帮助文档
帮助文档

runners · 变更

页面历史
runner api & ci 编写于 作者: Miykael_xxm's avatar Miykael_xxm
显示空白变更内容
内联 并排
Showing with 402 addition and 231 deletion
docs/api/runners.md
View page @ 34b6b6e1
# Runners API
## 注册和验证令牌
> 原文：[https://docs.gitlab.com/ee/api/runners.html](https://docs.gitlab.com/ee/api/runners.html)
将 Runner 与 CODE CHINA 连接时需要以下两个令牌(token)
- [Runners API](#runners-api)
- [Runners API](#runners-api-1)
- [Registration and authentication tokens](#registration-and-authentication-tokens)
- [List owned runners](#list-owned-runners)
- [List all runners](#list-all-runners)
- [Get runner’s details](#get-runners-details)
- [Update runner’s details](#update-runners-details)
- [Remove a runner](#remove-a-runner)
- [List runner’s jobs](#list-runners-jobs)
- [List project’s runners](#list-projects-runners)
- [Enable a runner in project](#enable-a-runner-in-project)
- [Disable a runner from project](#disable-a-runner-from-project)
- [List group’s runners](#list-groups-runners)
- [Register a new Runner](#register-a-new-runner)
- [Delete a registered Runner](#delete-a-registered-runner)
- [Verify authentication for a registered Runner](#verify-authentication-for-a-registered-runner)
# Runners API[](#runners-api "Permalink")
在 GitLab 8.5 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640)
## Registration and authentication tokens[](#registration-and-authentication-tokens "Permalink")
将 Runner 与 GitLab 连接时要考虑两个标记.
| Token | Description |
| 令牌 | 描述 |
| --- | --- |
| 注册令牌 | 用于[注册 Runner 的](https://docs.gitlab.com/runner/register/)令牌. 可以[通过 GitLab 获得](../ci/runners/README.html) . |
| 认证令牌 | 用于通过 GitLab 实例对 Runner 进行身份验证的令牌. 它可以在[注册 Runner](https://docs.gitlab.com/runner/register/)时自动获得，也可以[通过 Runners API](#register-a-new-runner)手动[注册时获得](#register-a-new-runner) . |
| 注册令牌 | 用于注册 Runner 的令牌. 可以[通过 CODE CHINA 获得](/docs/ci/runners) |
| 认证令牌 | 用于对 Runner 进行身份验证的令牌. 它可以在注册 Runner 时自动获得，也可以通过 Runners API 手动注册时获得|
这是在 Runner 注册中如何使用两个令牌的示例：
以下是在 Runner 注册中如何使用两个令牌的示例：
1. 您使用注册令牌通过 GitLab API 注册了 Runner，并返回了身份验证令牌.
2. 您使用该身份验证令牌并将其添加到[Runner 的配置文件中](https://docs.gitlab.com/runner/commands/) ：
1. 您使用注册令牌通过 API 注册了 Runner，并返回了认证令牌
2. 您使用该认证令牌并将其添加到 Runner 的配置文件中：
```
```yaml
[[runners]]
token = "<authentication_token>"
```
然后将 GitLab 和 Runner 连接起来.
然后将 CODE CHINA 和 Runner 连接起来。
## List owned runners[](#list-owned-runners "Permalink")
## 已拥有的 runners 列表
获取可供用户使用的特定跑步者的列表.
获取可供用户使用的特定 runners 的列表。
```
```bash
GET /runners
GET /runners?scope=active
GET /runners?type=project_type
......@@ -56,155 +32,262 @@ 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"
```
响应示例：
| `scope` | 字符串 | 否 | 不推荐使用: 用 `type` or `status` 代替. 要显示`active`, `paused`, `online`, `offline`中某一范围内的 runners；如果没有提供，则显示所有的 runners |
| `type` | 字符串 | 否 | 要显示的 runners 的类型，包括： `instance_type` ， `group_type` ， `project_type` |
| `status` | 字符串 | 否 | 要显示的 runners 状态，包括： `active` ， `paused` ， `online` ， `offline` |
| `tag_list` | 字符串数组 | 否 | 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[](#list-all-runners "Permalink")
获取 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"
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/api/v4/runners"
```
响应示例：
```
[ { "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-details "Permalink")
获取跑步者的详细信息.
```
```json
[
{
"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"
}
]
```
## 获取 runner 详情
获取 runner 的详细信息，只有在当前项目或组织中至少拥有`Maintainer`权限的用户才可以获取 runner 的详情。
```bash
GET /runners/:id
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `id` | integer | yes | 跑步者 ID |
| `id` | integer | 是 | runner ID |
```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/api/v4/runners/6"
```
**注意：**响应中的`token`属性[在 GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320)中已弃用. 并在[GitLab 13.0 中](https://gitlab.com/gitlab-org/gitlab/-/issues/214322)删除.
响应示例：
```
{ "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[](#update-runners-details "Permalink")
更新跑步者的详细信息.
```
```json
{
"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
}
```
## 更新 runner 详情
更新 runner 的详细信息。
```bash
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 处理作业的最大超时时间 |
| `id` | integer | 是 | runner ID |
| `description` | string | 否 | runner |
| `active` | boolean | 否 | runner 的状态； 可以设置为`true`或`false` |
| `tag_list` | array | 否 | runner 的标签列表； 放置标签数组，这些标签应最终分配给 runner |
| `run_untagged` | boolean | 否 | 指示 runner 可以执行未加标签的作业的标志 |
| `locked` | boolean | 否 | 指示 runner 被锁定的标志 |
| `access_level` | string | 否 | runner 的 access_level; `not_protected`或`ref_protected` |
| `maximum_timeout` | integer | 否 | 此 Runner 处理作业的最大超时时间 |
```bash
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
```
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](https://gitlab.com/gitlab-org/gitlab/-/issues/214320)中已弃用. 并在[GitLab 13.0 中](https://gitlab.com/gitlab-org/gitlab/-/issues/214322)删除.
响应示例：
```
{ "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[](#remove-a-runner "Permalink")
卸下流道.
```
DELETE /runners/:id
```
| Attribute | Type | Required | Description |
```json
{
"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
}
```
### 暂停 Runner
暂停指定的 runner 。
```bash
PUT --form "active=false" /runners/:runner_id
```
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `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[](#list-runners-jobs "Permalink")
| `id` | integer | 是 | runner ID |
在 GitLab 10.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) .
## 获取 runner 中的 jobs 列表
列出正在处理或由指定运行程序处理的作业.
列出正在处理或由指定 runner 处理的作业。
```
```bash
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` ） |
| `id` | integer | 是 | runner ID |
| `status` | string | 否 | 工作状态； 包括： `running` ， `success` ， `failed` ， `canceled` |
| `order_by` | string | 否 | 按`id`排序 |
| `sort` | string | 否 | 按`asc`或`desc`顺序对作业进行排序（默认值： `desc` ） |
```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/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-projects-runners "Permalink")
List all runners (specific and shared) available in the project. 列出项目中所有可用的跑步者（特定的和共享的）. Shared runners are listed if at least one shared runner is defined. 如果定义了至少一个共享运行程序，则列出共享运行程序.
```
```bash
[
{
"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"
}
}
]
```
## 获取项目的 runner 列表
列出项目中所有可用的 runner （特定的和共享的），如果定义了至少一个共享 runner，则列出共享 runner。
```bash
GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
......@@ -212,169 +295,257 @@ GET /projects/:id/runners?status=active
GET /projects/:id/runners?tag_list=tag1,tag2
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `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 | 跑步者标签列表 |
| `id` | integer/string | 是 | 经过身份验证的用户拥有的项目的 ID 或项目的 URL Path |
| `scope` | string | 否 | 不推荐使用：改为使用`type`或`status` ，要显示的特定 runner 的范围，包括： `active` ， `paused` ， `online` ， `offline` ； 显示所有 runner （如果未提供） |
| `type` | string | 否 | 要显示的 runner 的类型，包括： `instance_type` ， `group_type` ， `project_type` |
| `status` | string | 否 | 要显示的 runner 状态，包括： `active` ， `paused` ， `online` ， `offline` |
| `tag_list` | 字符串数组 | 否 | runner 标签列表 |
```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/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[](#enable-a-runner-in-project "Permalink")
在项目中启用可用的特定运行器.
```
```json
[
{
"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"
}
]
```
## 在项目中启用一个 runner
在项目中启用可用的特定 runner 。
```bash
POST /projects/:id/runners
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `runner_id` | integer | yes | 跑步者 ID |
| `id` | integer/string | 是 | 经过身份验证的用户拥有的项目的 ID 或项目的 URL Path |
| `runner_id` | integer | 是 | runner ID |
```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" --form "runner_id=9"
```bash
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/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" }
```json
{
"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-runner-from-project "Permalink")
## 在项目中禁用某一个 runner
禁用项目中的特定运行器. 仅当该项目不是与指定运行器关联的唯一项目时，它才有效. 如果是这样，则返回错误. 改用" [删除亚军"](#remove-a-runner)电话.
禁用项目中的特定 runner，仅当该项目不是与指定 runner 关联的唯一项目时，它才有效；否则返回错误，请改用 `删除 runner`命令。
```
```bash
DELETE /projects/:id/runners/:runner_id
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `runner_id` | integer | yes | 跑步者 ID |
| `id` | integer/string | 是 | 经过身份验证的用户拥有的项目的 ID 或项目的 URL Path |
| `runner_id` | integer | 是 | runner ID |
```
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"
```bash
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/api/v4/projects/9/runners/9"
```
## List group’s runners[](#list-groups-runners "Permalink")
## 获取组织中的 runner 列表
列出组中的所有跑步者（特定的和共享的）以及其祖先组. 如果定义了至少一个共享运行程序，则列出共享运行程序.
列出组中的所有 runner （特定的和共享的）以及其父组织，如果定义了至少一个共享 runner，则列出共享 runner。
```
```bash
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 | 跑步者标签列表 |
| `id` | integer | 是 | 认证用户拥有的组的 ID |
| `type` | string | 否 | 要显示的 runner 的类型，包括： `instance_type` ， `group_type` ， `project_type` |
| `status` | string | 否 | 要显示的 runner 状态，包括： `active` ， `paused` ， `online` ， `offline` |
| `tag_list` | 字符串数组 | 否 | runner 标签列表 |
```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
```bash
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/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[](#register-a-new-runner "Permalink")
为该实例注册一个新的运行器.
```json
[
{
"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"
}
]
```
## 注册一个 runner
为该实例注册一个新的运行器。
```
POST /runners
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `token` | string | yes | [Registration token](#registration-and-authentication-tokens). |
| `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 处理作业的最大超时时间 |
| `token` | string | 是 | [Registration token](#registration-and-authentication-tokens). |
| `description` | string | 否 | runner 的描述 |
| `info` | hash | 否 | runner 的元数据 |
| `active` | boolean | 否 | runner 是否活跃 |
| `locked` | boolean | 否 | Runner 是否应该为当前项目锁定 |
| `run_untagged` | boolean | 否 | runner 是否应处理未加标签的工作 |
| `tag_list` | 字符串数组 | 否 | runner 标签列表 |
| `access_level` | string | 否 | runner 的 access_level; `not_protected`或`ref_protected` |
| `maximum_timeout` | integer | 否 | 此 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"
curl --request POST "https://codechina.csdn.net/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"
```
Response:
响应:
| Status | Description |
| 状态码 | 描述 |
| --- | --- |
| 201 | 跑步者已创建 |
| 201 | runner 已创建 |
响应示例：
```json
{
"id": 12345,
"token": "6337ff461c94fd3fa32ba3b1ff4125"
}
```
{ "id": "12345", "token": "6337ff461c94fd3fa32ba3b1ff4125" }
```
## Delete a registered Runner[](#delete-a-registered-runner "Permalink")
## 删除某个 runner
可以通过以下两种方式删除某个已注册的 runner：
- 通过指定 runner ID 删除
- 通过指定 runner 的认证令牌删除
### 通过 runner ID 删除
删除注册的跑步者.
要按 ID 删除 runner，请使用你的访问令牌和 runner ID 进行删除：
```bash
DELETE /runners/:id
```
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `id` | integer | 是 | runner 的ID。在`项目设置 > CI/CD`下展开 Runners后可见，在 Remove Runner 按钮下方，是一个以 #号 开头的 ID，例如，`#6`。|
```bash
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://codechina.csdn.net/api/v4/runners/6"
```
### 通过认证令牌删除 runner
使用认证令牌删除某个 runner
```bash
DELETE /runners
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `token` | string | yes | Runner’s [authentication token](#registration-and-authentication-tokens). |
| `token` | string | 是 | runner 的认证令牌 |
```
curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>"
```bash
curl --request DELETE "https://codechina.csdn.net/api/v4/runners" \
--form "token=<authentication_token>"
```
Response:
相应:
| Status | Description |
| 状态码 | 描述 |
| --- | --- |
| 204 | 跑步者已被删除 |
| 204 | runner 已被删除 |
## Verify authentication for a registered Runner[](#verify-authentication-for-a-registered-runner "Permalink")
## 验证 runner 的认证令牌
验证注册的运行程序的身份验证凭据.
验证注册 runner 的身份验证凭据。
```
```bash
POST /runners/verify
```
| Attribute | Type | Required | Description |
| 属性 | 类型 | 必需的 | 描述 |
| --- | --- | --- | --- |
| `token` | string | yes | Runner’s [authentication token](#registration-and-authentication-tokens). |
| `token` | string | 是 | runner 的认证令牌 |
```
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>"
```bash
curl --request POST "https://codechina.csdn.net/api/v4/runners/verify" --form "token=<authentication_token>"
```
Response:
响应:
| Status | Description |
| 状态码 | 描述 |
| --- | --- |
| 200 | 凭证有效 |
| 403 | 凭证无效 |
\ No newline at end of file