- 注册和身份验证令牌
- 列出拥有的 runner
- 列出所有 runner
- 获取 runner 的详细信息
- 更新 runner 的详细信息
- 列出由 runner 处理的作业
- 列出 runner 的管理器
- 列出项目的 runner
- 将 runner 分配给项目
- 从项目中取消分配 runner
- 列出群组的 runner
- 创建 runner
- 删除 runner
- 验证已注册 runner 的身份验证
- 重置实例的 runner 注册令牌
- 重置项目的 runner 注册令牌
- 重置群组的 runner 注册令牌
- 通过使用 runner ID 重置 runner 的认证令牌
- 通过使用当前令牌重置 runner 的认证令牌
{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: JihuLab.com, 极狐GitLab私有化部署, 极狐GitLab Dedicated
{{< /details >}}
本文档描述了注册到实例的 runner 的端点。要创建与当前用户链接的 runner,请参阅创建 runner。
分页适用于以下 API 端点(默认返回 20 个项目):
GET /runners
GET /runners/all
GET /runners/:id/jobs
GET /projects/:id/runners
GET /groups/:id/runners
注册和身份验证令牌
要将 runner 连接到极狐GitLab,您需要两个令牌。
令牌 | 描述 |
---|---|
注册令牌 | 用于注册 runner的令牌。可以通过极狐GitLab获得](../ci/runners/_index.md)。 |
身份验证令牌 | 用于与极狐GitLab实例验证 runner 的令牌。该令牌在您注册 runner时自动获取,或者在您手动注册 runner或重置身份验证令牌时由 Runners API 获取。您还可以通过使用POST /user/runners 端点获得令牌。 |
以下是如何使用令牌注册 runner 的示例:
- 使用注册令牌通过极狐GitLab API 注册 runner,以接收身份验证令牌。
-
将身份验证令牌添加到runner 的配置文件中:
[[runners]] token = "<authentication_token>"
极狐GitLab 和 runner 现在已连接。
列出拥有的 runner
获取用户可用的 runner 列表。
先决条件:
- 您必须是目标命名空间或项目的管理员或具有所有者角色。
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。
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
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
scope |
string | no | 已弃用:使用 type 或 status 代替。要返回的 runner 范围之一:active 、paused 、online 和 offline ;如果未提供则显示所有 runner |
type |
string | no | 要返回的 runner 类型之一:instance_type 、group_type 、project_type
|
status |
string | no | 要返回的 runner 状态之一:online 、offline 、stale 或 never_contacted 。其他可能的值是已弃用的 active 和 paused 。请求 offline runner 可能还会返回 stale runner 因为 stale 包含在 offline 中。 |
paused |
boolean | no | 是否仅包含接受或忽略新作业的 runner |
tag_list |
string array | no | runner 标签列表 |
version_prefix |
string | no | 要返回的 runner 版本前缀。例如,15.0 、14 、16.1.241
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
{{< alert type=”warning” >}}
status
查询参数中的 active
和 paused
值已弃用,并计划在未来版本的 REST API中删除。请改用 paused
查询参数。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 active
属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
[
{
"active": true,
"paused": false,
"description": "test-1-20150125",
"id": 6,
"ip_address": "",
"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": "",
"is_shared": false,
"runner_type": "group_type",
"name": null,
"online": false,
"status": "offline"
}
]
列出所有 runner
{{< details >}}
- Tier: 基础版, 专业版, 旗舰版
- Offering: 极狐GitLab私有化部署, 极狐GitLab Dedicated
{{< /details >}}
获取极狐GitLab实例中所有 runner 的列表(项目和共享)。访问权限仅限于具有管理员访问权限的用户。
先决条件:
- 您必须是目标命名空间或项目的管理员或具有所有者角色。
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。
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
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
scope |
string | no | 已弃用:使用 type 或 status 代替。要返回的 runner 范围之一:specific 、shared 、active 、paused 、online 和 offline ;如果未提供则显示所有 runner |
type |
string | no | 要返回的 runner 类型之一:instance_type 、group_type 、project_type
|
status |
string | no | 要返回的 runner 状态之一:online 、offline 、stale 或 never_contacted 。其他可能的值是已弃用的 active 和 paused 。请求 offline runner 可能还会返回 stale runner 因为 stale 包含在 offline 中。 |
paused |
boolean | no | 是否仅包含接受或忽略新作业的 runner |
tag_list |
string array | no | runner 标签列表 |
version_prefix |
string | no | 要返回的 runner 版本前缀。例如,15.0 、16.1.241
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
{{< alert type=”warning” >}}
status
查询参数中的 active
和 paused
值已弃用,并计划在未来版本的 REST API中删除。请改用 paused
查询参数。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 active
属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
[
{
"active": true,
"paused": false,
"description": "shared-runner-1",
"id": 1,
"ip_address": "",
"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": "",
"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": "",
"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": "",
"is_shared": false,
"runner_type": "group_type",
"name": null,
"online": false,
"status": "offline"
}
]
要查看超过前 20 个 runner,请使用分页。
获取 runner 的详细信息
获取 runner 的详细信息。
通过此端点的实例 runner 详细信息对所有经过身份验证的用户可用。
先决条件:
- 您必须至少拥有目标命名空间或项目的开发者角色。
- 具有
manage_runner
范围和适当角色的访问令牌。
GET /runners/:id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | runner 的 ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
{{< alert type=”warning” >}}
响应中的 active
属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
{{< alert type=”note” >}}
响应中的 version
、revision
、platform
和 architecture
属性在极狐GitLab 17.0中已弃用,并计划在未来版本的 REST API中删除。相同的属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
{
"active": true,
"paused": false,
"architecture": null,
"description": "test-1-20150125",
"id": 6,
"ip_address": "",
"is_shared": false,
"runner_type": "project_type",
"contacted_at": "2016-01-25T16:39:48.066Z",
"maintenance_note": null,
"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 的详细信息。
PUT /runners/:id
先决条件:
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。 - 具有
manage_runner
范围和适当角色的访问令牌。
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | runner 的 ID |
description |
string | no | runner 的描述 |
active |
boolean | no | 已弃用:请改用 paused 。标志指示 runner 是否允许接收作业 |
paused |
boolean | no | 指定 runner 是否应忽略新作业 |
tag_list |
array | no | runner 的标签列表 |
run_untagged |
boolean | no | 指定 runner 是否可以执行未标记的作业 |
locked |
boolean | no | 指定 runner 是否被锁定 |
access_level |
string | no | runner 的访问级别;not_protected 或 ref_protected
|
maximum_timeout |
integer | no | 限制 runner 可以运行作业的时间(以秒为单位)的最大超时时间 |
maintenance_note |
string | no | runner 的自由格式维护备注(1024 个字符) |
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"
{{< alert type=”warning” >}}
active
查询参数已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
{
"active": true,
"architecture": null,
"description": "test-1-20150125-test",
"id": 6,
"ip_address": "",
"is_shared": false,
"runner_type": "group_type",
"contacted_at": "2016-01-25T16:39:48.066Z",
"maintenance_note": null,
"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。
先决条件:
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。 - 具有
manage_runner
范围和适当角色的访问令牌。
PUT --form "paused=true" /runners/:runner_id
# --或--
# 已弃用:计划在 16.0 中删除
PUT --form "active=false" /runners/:runner_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
runner_id |
integer | yes | runner 的 ID |
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "paused=true" "https://gitlab.example.com/api/v4/runners/6"
# --或--
# 已弃用:计划在 16.0 中删除
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "active=false" "https://gitlab.example.com/api/v4/runners/6"
{{< alert type=”warning” >}}
active
表单属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
列出由 runner 处理的作业
列出指定 runner 正在处理或已处理的作业。作业列表仅限于用户在其中至少拥有报告者角色的项目。
GET /runners/:id/jobs
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | runner 的 ID |
system_id |
string | no | runner 管理器正在运行的机器的系统 ID |
status |
string | no | 作业的状态;之一:running 、success 、failed 、canceled
|
order_by |
string | no | 按 id 排序作业 |
sort |
string | no | 按 asc 或 desc 顺序排序作业(默认:desc )。如果指定了 sort ,则也必须指定 order_by
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/jobs?status=running"
示例响应:
[
{
"id": 2,
"status": "running",
"stage": "test",
"name": "test",
"ref": "main",
"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,
"queued_duration": 2,
"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": "main",
"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 的所有管理器。
GET /runners/:id/managers
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | runner 的 ID |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/1/managers"
示例响应:
[
{
"id": 1,
"system_id": "s_89e5e9956577",
"version": "16.11.1",
"revision": "535ced5f",
"platform": "linux",
"architecture": "amd64",
"created_at": "2024-06-09T11:12:02.507Z",
"contacted_at": "2024-06-09T06:30:09.355Z",
"ip_address": "127.0.0.1",
"status": "offline"
},
{
"id": 2,
"system_id": "runner-2",
"version": "16.11.0",
"revision": "91a27b2a",
"platform": "linux",
"architecture": "amd64",
"created_at": "2024-06-09T09:12:02.507Z",
"contacted_at": "2024-06-09T06:30:09.355Z",
"ip_address": "127.0.0.1",
"status": "offline",
}
]
列出项目的 runner
列出项目中可用的所有 runner,包括祖先群组和任何允许的实例 runner。
先决条件:
- 您必须是目标项目的管理员或至少拥有维护者角色。
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
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | yes | 项目的 ID 或URL 编码路径 |
scope |
string | no | 已弃用:使用 type 或 status 代替。要返回的 runner 范围之一:active 、paused 、online 和 offline ;如果未提供则显示所有 runner |
type |
string | no | 要返回的 runner 类型之一:instance_type 、group_type 、project_type
|
status |
string | no | 要返回的 runner 状态之一:online 、offline 、stale 或 never_contacted 。其他可能的值是已弃用的 active 和 paused 。请求 offline runner 可能还会返回 stale runner 因为 stale 包含在 offline 中。 |
paused |
boolean | no | 是否仅包含接受或忽略新作业的 runner |
tag_list |
string array | no | runner 标签列表 |
version_prefix |
string | no | 要返回的 runner 版本前缀。例如,15.0 、14 、16.1.241
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
{{< alert type=”warning” >}}
status
查询参数中的 active
和 paused
值已弃用,并计划在未来版本的 REST API中删除。请改用 paused
查询参数。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 active
属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
[
{
"active": true,
"paused": false,
"description": "test-2-20150125",
"id": 8,
"ip_address": "",
"is_shared": false,
"runner_type": "project_type",
"name": null,
"online": false,
"status": "offline"
},
{
"active": true,
"paused": false,
"description": "development_runner",
"id": 5,
"ip_address": "",
"is_shared": true,
"runner_type": "instance_type",
"name": null,
"online": true,
"status": "online"
}
]
将 runner 分配给项目
将可用的项目 runner 分配给项目。
先决条件:
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。
POST /projects/:id/runners
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | yes | 项目的 ID 或URL 编码路径 |
runner_id |
integer | yes | runner 的 ID |
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners" \
--form "runner_id=9"
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab 17.0 中,该属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
{
"active": true,
"description": "test-2016-02-01",
"id": 9,
"ip_address": "",
"is_shared": false,
"runner_type": "project_type",
"name": null,
"online": true,
"status": "online"
}
从项目中取消分配 runner
从项目中取消分配项目 runner。您无法从拥有者项目中取消分配 runner。如果尝试此操作,则会发生错误。请改用调用删除 runner。
先决条件:
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。
DELETE /projects/:id/runners/:runner_id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer/string | yes | 项目的 ID 或URL 编码路径 |
runner_id |
integer | yes | runner 的 ID |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9"
列出群组的 runner
列出群组及其祖先群组中可用的所有 runner,包括任何允许的实例 runner。
先决条件:
- 您必须是目标命名空间的管理员或拥有维护者角色。
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
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | 群组的 ID |
type |
string | no | 要返回的 runner 类型之一:instance_type 、group_type 、project_type 。project_type 值是已弃用 并计划在极狐GitLab 15.0 中删除 |
status |
string | no | 要返回的 runner 状态之一:online 、offline 、stale 或 never_contacted 。其他可能的值是已弃用的 active 和 paused 。请求 offline runner 可能还会返回 stale runner 因为 stale 包含在 offline 中。 |
paused |
boolean | no | 是否仅包含接受或忽略新作业的 runner |
tag_list |
string array | no | runner 标签列表 |
version_prefix |
string | no | 要返回的 runner 版本前缀。例如,15.0 、14 、16.1.241
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
{{< alert type=”warning” >}}
status
查询参数中的 active
和 paused
值已弃用,并计划在未来版本的 REST API中删除。请改用 paused
查询参数。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 active
属性已弃用,并计划在未来版本的 REST API中删除。请改用 paused
属性。
{{< /alert >}}
{{< alert type=”warning” >}}
响应中的 ip_address
属性在极狐GitLab 16.1中已弃用,并计划在未来版本的 REST API中删除。在极狐GitLab中,t 属性返回一个空字符串。ipAddress
属性可以在相应的 runner 管理器中找到。它只能通过 GraphQL 的CiRunnerManager
类型获得。
{{< /alert >}}
示例响应:
[
{
"id": 3,
"description": "Shared",
"ip_address": "",
"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": "",
"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": "",
"active": true,
"paused": false,
"is_shared": false,
"runner_type": "group_type",
"name": "gitlab-runner",
"online": null,
"status": "never_contacted"
}
]
创建 runner
{{< alert type=”warning” >}}
如果项目或群组设置中禁用了使用 runner 注册令牌的注册,则此端点返回 HTTP 410 Gone
状态代码。如果禁用了使用 runner 注册令牌的注册,请使用POST /user/runners
端点来创建和注册 runner。
{{< /alert >}}
使用 runner 注册令牌创建 runner。
POST /runners
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
token |
string | yes | 注册令牌 |
description |
string | no | runner 的描述 |
info |
hash | no | runner 的元数据。您可以包含 name 、version 、revision 、platform 和 architecture ,但只有 version 、platform 和 architecture 显示在 UI 的管理员区域 |
active |
boolean | no | 已弃用:请改用 paused 。指定 runner 是否允许接收新作业 |
paused |
boolean | no | 指定 runner 是否应忽略新作业 |
locked |
boolean | no | 指定 runner 是否应锁定当前项目 |
run_untagged |
boolean | no | 指定 runner 是否应处理未标记的作业 |
tag_list |
string array | no | runner 标签列表 |
access_level |
string | no | runner 的访问级别;not_protected 或 ref_protected
|
maximum_timeout |
integer | no | 限制 runner 可以运行作业的时间(以秒为单位)的最大超时时间 |
maintainer_note |
string | no |
已弃用,请参见 maintenance_note
|
maintenance_note |
string | no | runner 的自由格式维护备注(1024 个字符) |
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"
响应:
状态 | 描述 |
---|---|
201 | runner 已创建 |
403 | runner 注册令牌无效 |
410 | runner 注册已禁用 |
示例响应:
{
"id": 12345,
"token": "6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
}
删除 runner
您可以通过指定以下内容来删除 runner:
- runner ID
- runner 的身份验证令牌
通过 ID 删除 runner
要通过 ID 删除 runner,请使用您的访问令牌和 runner 的 ID:
先决条件:
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。 - 具有
manage_runner
范围和适当角色的访问令牌。
DELETE /runners/:id
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | yes | runner 的 ID。ID 可在 UI 中设置 > CI/CD下看到。展开Runners,在删除 runner下是一个由井号(#)标识的 ID,例如 #6 。 |
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
通过身份验证令牌删除 runner
要通过使用 runner 的身份验证令牌删除 runner:
先决条件:
- 您必须是目标命名空间或项目的管理员或拥有所有者角色。
- 对于
instance_type
,您必须是极狐GitLab实例的管理员。
DELETE /runners
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
token |
string | yes | runner 的身份验证令牌。 |
curl --request DELETE "https://gitlab.example.com/api/v4/runners" \
--form "token=<authentication_token>"
响应:
状态 | 描述 |
---|---|
204 | runner 已删除 |
验证已注册 runner 的身份验证
验证已注册 runner 的身份验证凭证。
POST /runners/verify
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
token |
string | yes | runner 的身份验证令牌。 |
system_id |
string | no | runner 的系统标识符。如果 token 以 glrt- 开头,则需要此属性。 |
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
--form "token=<authentication_token>"
Status | Description |
---|---|
200 | Credentials are valid |
403 | Credentials are invalid |
示例响应:
{
"id": 12345,
"token": "glrt-6337ff461c94fd3fa32ba3b1ff4125",
"token_expires_at": "2021-09-27T21:05:03.203Z"
}
重置实例的 runner 注册令牌
{{< alert type=”warning” >}}
在极狐GitLab 15.6 中,传递 runner 注册令牌的选项和对某些配置参数的支持已被废弃,计划在极狐GitLab 20.0 中移除。使用 runner 创建工作流生成一个认证令牌来注册 runners。这个过程提供了对 runner 所有权的完全可追溯性,并增强了 runner 队列的安全性。
更多信息,请参阅迁移到新的 runner 注册工作流。
{{< /alert >}}
重置极狐GitLab 实例的 runner 注册令牌。
POST /runners/reset_registration_token
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/runners/reset_registration_token"
重置项目的 runner 注册令牌
{{< alert type=”warning” >}}
在极狐GitLab 15.6 中,传递 runner 注册令牌的选项和对某些配置参数的支持已被废弃,计划在极狐GitLab 20.0 中移除。使用 runner 创建工作流生成一个认证令牌来注册 runners。这个过程提供了对 runner 所有权的完全可追溯性,并增强了 runner 队列的安全性。更多信息,请参阅迁移到新的 runner 注册工作流。
{{< /alert >}}
重置项目的 runner 注册令牌。
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"
重置群组的 runner 注册令牌
{{< alert type=”warning” >}}
在极狐GitLab 15.6 中,传递 runner 注册令牌的选项和对某些配置参数的支持已被废弃,计划在极狐GitLab 20.0 中移除。使用 runner 创建工作流生成一个认证令牌来注册 runners。这个过程提供了对 runner 所有权的完全可追溯性,并增强了 runner 队列的安全性。更多信息,请参阅迁移到新的 runner 注册工作流。
{{< /alert >}}
重置群组的 runner 注册令牌。
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"
通过使用 runner ID 重置 runner 的认证令牌
通过使用 runner ID 重置 runner 的认证令牌。
先决条件:
- 对于
instance_type
,您必须是极狐GitLab 实例的管理员。 - 对于
group_type
,您必须拥有目标命名空间的所有者角色。 - 对于
project_type
,您必须至少拥有目标项目的维护者角色。 - 一个具有
manage_runner
范围和适当角色的访问令牌。
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"
}
通过使用当前令牌重置 runner 的认证令牌
通过使用当前令牌的值作为输入重置 runner 的认证令牌。
POST /runners/reset_authentication_token
Attribute | Type | Required | Description |
---|---|---|---|
token |
string | yes | The authentication 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"
}