Runners API

使用此 API 管理注册到实例的 runners。

要创建新的实例、群组或项目 runner，请使用 POST /user/runners 端点。 使用此 API 管理现有 runner。

以下 API 端点支持分页（默认返回 20 项）：

plaintext
GET /runners
GET /runners/all
GET /runners/:id/jobs
GET /projects/:id/runners
GET /groups/:id/runners

注册和认证令牌#

要连接 runner 与极狐GitLab，您需要两个令牌。

以下是如何使用令牌进行 runner 注册的示例：

1. 使用极狐GitLab API 通过注册令牌注册 runner 以接收认证令牌。

2. 将认证令牌添加到 runner 的配置文件：

   toml
   [[runners]]
     token = "<authentication_token>"

随后极狐GitLab 和 runner 即连接成功。

列出所有可用的 runner#

列出用户可用的所有 runner。

前提条件：

• 对于群组 runner，您必须在所有者命名空间中具有所有者角色。
• 对于项目 runner，您必须在分配给 runner 的项目中具有安全管理员、维护者或所有者角色。

plaintext
1GET /runners
2GET /runners?scope=active
3GET /runners?type=project_type
4GET /runners?status=online
5GET /runners?paused=true
6GET /runners?tag_list=tag1,tag2

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

示例响应：

json
1[
2    {
3        "active": true,
4        "paused": false,
5        "description": "test-1-20150125",
6        "id": 6,
7        "ip_address": "",
8        "is_shared": false,
9        "runner_type": "project_type",
10        "name": null,
11        "online": true,
12        "status": "online",
13        "job_execution_status": "idle"
14    },
15    {
16        "active": true,
17        "paused": false,
18        "description": "test-2-20150125",
19        "id": 8,
20        "ip_address": "",
21        "is_shared": false,
22        "runner_type": "group_type",
23        "name": null,
24        "online": false,
25        "status": "offline",
26        "job_execution_status": "idle"
27    }
28]

列出所有 runner#

列出极狐GitLab 实例中的所有 runner（项目和共享 runner）。

前提条件：

• 您必须具有管理员访问权限或审计员访问权限。

plaintext
1GET /runners/all
2GET /runners/all?scope=online
3GET /runners/all?type=project_type
4GET /runners/all?status=online
5GET /runners/all?paused=true
6GET /runners/all?tag_list=tag1,tag2

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

示例响应：

json
1[
2    {
3        "active": true,
4        "paused": false,
5        "description": "shared-runner-1",
6        "id": 1,
7        "ip_address": "",
8        "is_shared": true,
9        "runner_type": "instance_type",
10        "name": null,
11        "online": true,
12        "status": "online",
13        "job_execution_status": "idle"
14    },
15    {
16        "active": true,
17        "paused": false,
18        "description": "shared-runner-2",
19        "id": 3,
20        "ip_address": "",
21        "is_shared": true,
22        "runner_type": "instance_type",
23        "name": null,
24        "online": false,
25        "status": "offline",
26        "job_execution_status": "idle"
27    },
28    {
29        "active": true,
30        "paused": false,
31        "description": "test-1-20150125",
32        "id": 6,
33        "ip_address": "",
34        "is_shared": false,
35        "runner_type": "project_type",
36        "name": null,
37        "online": true,
38        "status": "paused",
39        "job_execution_status": "idle"
40    },
41    {
42        "active": true,
43        "paused": false,
44        "description": "test-2-20150125",
45        "id": 8,
46        "ip_address": "",
47        "is_shared": false,
48        "runner_type": "group_type",
49        "name": null,
50        "online": false,
51        "status": "offline",
52        "job_execution_status": "idle"
53    }
54]

要查看前 20 个之后的 runner，请使用分页。

获取 runner 详情#

获取 runner 的详细信息。

实例 runner 详情通过此端点对所有已认证用户可用。

前提条件：

• 用户访问权限：您必须具有以下之一：
  • 对于群组 runner：在所有者命名空间中具有维护者或所有者角色。
  • 对于项目 runner：在拥有该 runner 的项目中具有安全管理员、维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围及相应角色的访问令牌。

plaintext
GET /runners/:id

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

示例响应：

json
1{
2    "active": true,
3    "paused": false,
4    "architecture": null,
5    "description": "test-1-20150125",
6    "id": 6,
7    "ip_address": "",
8    "is_shared": false,
9    "runner_type": "project_type",
10    "contacted_at": "2016-01-25T16:39:48.066Z",
11    "maintenance_note": null,
12    "name": null,
13    "online": true,
14    "status": "online",
15    "job_execution_status": "idle",
16    "platform": null,
17    "projects": [
18        {
19            "id": 1,
20            "name": "极狐GitLab 基础版",
21            "name_with_namespace": "极狐GitLab.org / 极狐GitLab 基础版",
22            "path": "gitlab-foss",
23            "path_with_namespace": "gitlab-org/gitlab-foss"
24        }
25    ],
26    "revision": null,
27    "tag_list": [
28        "ruby",
29        "mysql"
30    ],
31    "version": null,
32    "access_level": "ref_protected",
33    "maximum_timeout": 3600
34}

更新 runner 详情#

更新 runner 的详细信息。

plaintext
PUT /runners/:id

前提条件：

• 用户访问权限：您必须具有以下之一：
  • 对于实例 runner：对极狐GitLab 实例具有管理员访问权限。
  • 对于群组 runner：在所有者命名空间中具有所有者角色。
  • 对于项目 runner：在分配给 runner 的项目中具有维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围及相应角色的访问令牌。

shell
curl --request PUT \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/6" \
     --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

示例响应：

json
1{
2    "active": true,
3    "architecture": null,
4    "description": "test-1-20150125-test",
5    "id": 6,
6    "ip_address": "",
7    "is_shared": false,
8    "runner_type": "group_type",
9    "contacted_at": "2016-01-25T16:39:48.066Z",
10    "maintenance_note": null,
11    "name": null,
12    "online": true,
13    "status": "online",
14    "job_execution_status": "idle",
15    "platform": null,
16    "projects": [
17        {
18            "id": 1,
19            "name": "极狐GitLab 基础版",
20            "name_with_namespace": "极狐GitLab.org / 极狐GitLab 基础版",
21            "path": "gitlab-foss",
22            "path_with_namespace": "gitlab-org/gitlab-foss"
23        }
24    ],
25    "revision": null,
26    "tag_list": [
27        "ruby",
28        "mysql",
29        "tag1",
30        "tag2"
31    ],
32    "version": null,
33    "access_level": "ref_protected",
34    "maximum_timeout": null
35}

暂停一个 runner#

暂停一个 runner。

前提条件：

• 用户访问权限：您必须具有以下之一：
  • 对于实例 runner：对极狐GitLab 实例具有管理员访问权限。
  • 对于群组 runner：在所有者命名空间中具有所有者角色。
  • 对于项目 runner：在分配给 runner 的项目中具有维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围及相应角色的访问令牌。

plaintext
1PUT --form "paused=true" /runners/:runner_id
2
3# --或--
4
5# 已弃用：计划在 16.0 中移除
6PUT --form "active=false" /runners/:runner_id

shell
1curl --request PUT \
2     --header "PRIVATE-TOKEN: <your_access_token>" \
3     --form "paused=true"  \
4     --url "https://gitlab.example.com/api/v4/runners/6"
5
6# --或--
7
8# 已弃用：计划在 16.0 中移除
9curl --request PUT \
10     --header "PRIVATE-TOKEN: <your_access_token>" \
11     --form "active=false"  \
12     --url "https://gitlab.example.com/api/v4/runners/6"

列出 runner 处理的所有作业#

列出指定 runner 正在处理或已处理的所有作业。作业列表仅限于用户具有报告者、开发者、维护者或所有者角色的项目。

plaintext
GET /runners/:id/jobs

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

示例响应：

json
1[
2    {
3        "id": 2,
4        "status": "running",
5        "stage": "test",
6        "name": "test",
7        "ref": "main",
8        "tag": false,
9        "coverage": null,
10        "created_at": "2017-11-16T08:50:29.000Z",
11        "started_at": "2017-11-16T08:51:29.000Z",
12        "finished_at": "2017-11-16T08:53:29.000Z",
13        "duration": 120,
14        "queued_duration": 2,
15        "user": {
16            "id": 1,
17            "name": "John Doe2",
18            "username": "user2",
19            "state": "active",
20            "avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
21            "web_url": "http://localhost/user2",
22            "created_at": "2017-11-16T18:38:46.000Z",
23            "bio": null,
24            "location": null,
25            "public_email": "",
26            "linkedin": "",
27            "twitter": "",
28            "website_url": "",
29            "organization": null
30        },
31        "commit": {
32            "id": "97de212e80737a608d939f648d959671fb0a0142",
33            "short_id": "97de212e",
34            "title": "Update configuration\r",
35            "created_at": "2017-11-16T08:50:28.000Z",
36            "parent_ids": [
37                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
38                "498214de67004b1da3d820901307bed2a68a8ef6"
39            ],
40            "message": "See merge request !123",
41            "author_name": "John Doe2",
42            "author_email": "user2@example.org",
43            "authored_date": "2017-11-16T08:50:27.000Z",
44            "committer_name": "John Doe2",
45            "committer_email": "user2@example.org",
46            "committed_date": "2017-11-16T08:50:27.000Z"
47        },
48        "pipeline": {
49            "id": 2,
50            "sha": "97de212e80737a608d939f648d959671fb0a0142",
51            "ref": "main",
52            "status": "running"
53        },
54        "project": {
55            "id": 1,
56            "description": null,
57            "name": "project1",
58            "name_with_namespace": "John Doe2 / project1",
59            "path": "project1",
60            "path_with_namespace": "namespace1/project1",
61            "created_at": "2017-11-16T18:38:46.620Z"
62        }
63    }
64]

列出 runner 的所有管理器#

列出 runner 的所有管理器。

plaintext
GET /runners/:id/managers

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/runners/1/managers"

示例响应：

json
1[
2    {
3      "id": 1,
4      "system_id": "s_89e5e9956577",
5      "version": "16.11.1",
6      "revision": "535ced5f",
7      "platform": "linux",
8      "architecture": "amd64",
9      "created_at": "2024-06-09T11:12:02.507Z",
10      "contacted_at": "2024-06-09T06:30:09.355Z",
11      "ip_address": "127.0.0.1",
12      "status": "offline",
13      "job_execution_status": "idle"
14    },
15    {
16      "id": 2,
17      "system_id": "runner-2",
18      "version": "16.11.0",
19      "revision": "91a27b2a",
20      "platform": "linux",
21      "architecture": "amd64",
22      "created_at": "2024-06-09T09:12:02.507Z",
23      "contacted_at": "2024-06-09T06:30:09.355Z",
24      "ip_address": "127.0.0.1",
25      "status": "offline",
26      "job_execution_status": "idle"
27    }
28]

列出项目的所有 runner#

列出项目中所有可用的 runner，包括来自祖先群组和任何允许的实例 runner。

前提条件：

• 您必须是极狐GitLab 实例的管理员，或者对于目标项目至少具有维护者或审计员角色。

plaintext
1GET /projects/:id/runners
2GET /projects/:id/runners?scope=active
3GET /projects/:id/runners?type=project_type
4GET /projects/:id/runners?status=online
5GET /projects/:id/runners?paused=true
6GET /projects/:id/runners?tag_list=tag1,tag2

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

示例响应：

json
1[
2    {
3        "active": true,
4        "paused": false,
5        "description": "test-2-20150125",
6        "id": 8,
7        "ip_address": "",
8        "is_shared": false,
9        "runner_type": "project_type",
10        "name": null,
11        "online": false,
12        "status": "offline",
13        "job_execution_status": "idle"
14    },
15    {
16        "active": true,
17        "paused": false,
18        "description": "development_runner",
19        "id": 5,
20        "ip_address": "",
21        "is_shared": true,
22        "runner_type": "instance_type",
23        "name": null,
24        "online": true,
25        "status": "online",
26        "job_execution_status": "idle"
27    }
28]

将 Runner 分配给项目#

将可用的项目 Runner 分配给项目。

先决条件：

• 用户访问权限：您必须具有以下之一：
  • 在拥有该 Runner 的源项目和目标项目中具有维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。

plaintext
POST /projects/:id/runners

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

示例响应：

json
1{
2    "active": true,
3    "description": "test-2016-02-01",
4    "id": 9,
5    "ip_address": "",
6    "is_shared": false,
7    "runner_type": "project_type",
8    "name": null,
9    "online": true,
10    "status": "online",
11    "job_execution_status": "idle"
12}

从项目中取消分配 Runner#

从项目中取消分配项目 Runner。 您不能从所属项目中取消分配 Runner。如果尝试此操作，会发生错误。 请改用 删除 Runner 的调用。

先决条件：

• 您不能锁定该 Runner，除非您是管理员。
• 用户访问权限：您必须具有以下之一：
  • 在要取消分配的项目中具有维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
DELETE /projects/:id/runners/:runner_id

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

列出群组的所有 Runner#

列出群组及其上级群组中所有可用的 Runner，包括 任何允许的实例 Runner。

先决条件：

• 用户访问权限：您必须具有以下之一：
  • 极狐GitLab 实例的管理员访问权限。
  • 在群组中具有所有者或审计员角色。
  • 在群组中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
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

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

示例响应：

json
1[
2  {
3    "id": 3,
4    "description": "Shared",
5    "ip_address": "",
6    "active": true,
7    "paused": false,
8    "is_shared": true,
9    "runner_type": "instance_type",
10    "name": "gitlab-runner",
11    "online": null,
12    "status": "never_contacted",
13    "job_execution_status": "idle"
14  },
15  {
16    "id": 6,
17    "description": "Test",
18    "ip_address": "",
19    "active": true,
20    "paused": false,
21    "is_shared": true,
22    "runner_type": "instance_type",
23    "name": "gitlab-runner",
24    "online": false,
25    "status": "offline",
26    "job_execution_status": "idle"
27  },
28  {
29    "id": 8,
30    "description": "Test 2",
31    "ip_address": "",
32    "active": true,
33    "paused": false,
34    "is_shared": false,
35    "runner_type": "group_type",
36    "name": "gitlab-runner",
37    "online": null,
38    "status": "never_contacted",
39    "job_execution_status": "idle"
40  }
41]

创建 Runner#

使用 Runner 注册令牌创建 Runner。

如果在项目或群组设置中禁用了使用 Runner 注册令牌进行注册， 此端点将返回 HTTP 410 Gone 状态码。如果使用 Runner 注册令牌进行注册被禁用， 请改用 POST /user/runners 端点来创建和注册 Runner。

plaintext
POST /runners

shell
curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<registration_token>" --form "description=test-1-20150125-test" \
     --form "tag_list=ruby,mysql,tag1,tag2"

响应：

示例响应：

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

删除 Runner#

您可以通过指定以下内容来删除 Runner：

• Runner ID
• Runner 的认证令牌

通过 ID 删除 Runner#

要通过 ID 删除 Runner，请使用您的访问令牌和 Runner 的 ID：

先决条件：

• 用户访问权限：您必须具有以下之一：
  • 对于实例 Runner：极狐GitLab 实例的管理员访问权限。
  • 对于群组 Runner：所有者命名空间中的所有者角色。
  • 对于项目 Runner：在拥有该 Runner 的项目中具有维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
DELETE /runners/:id

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

通过认证令牌删除 Runner#

使用其认证令牌删除 Runner。

plaintext
DELETE /runners

shell
curl --request DELETE \
     --url "https://gitlab.example.com/api/v4/runners" \
     --form "token=<authentication_token>"

响应：

验证已注册 Runner 的认证信息#

验证已注册 Runner 的认证凭据。

plaintext
POST /runners/verify

shell
curl --request POST \
     --url "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

响应：

示例响应：

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

重置实例的 Runner 注册令牌#

重置极狐GitLab 实例的 Runner 注册令牌。

plaintext
POST /runners/reset_registration_token

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

重置项目的 Runner 注册令牌#

重置项目的 Runner 注册令牌。

plaintext
POST /projects/:id/runners/reset_registration_token

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

重置群组的 Runner 注册令牌#

重置群组的 Runner 注册令牌。

plaintext
POST /groups/:id/runners/reset_registration_token

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

使用 Runner ID 重置 Runner 的认证令牌#

通过使用其 Runner ID 重置 Runner 的认证令牌。

先决条件：

• 用户访问权限：您必须具有以下之一：
  • 对于实例 Runner：极狐GitLab 实例的管理员访问权限。
  • 对于群组 Runner：所有者命名空间中的所有者角色。
  • 对于项目 Runner：分配给 Runner 的项目中的维护者或所有者角色。
  • 在相关群组或项目中具有 admin_runners 权限的自定义角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
POST /runners/:id/reset_authentication_token

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

示例响应：

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

使用当前令牌重置 Runner 的认证令牌#

通过使用当前令牌值作为输入来重置 Runner 的认证令牌。

plaintext
POST /runners/reset_authentication_token

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

示例响应：

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

发现 Job Router 信息#

版本历史

• 引入于极狐GitLab 18.7 带有功能标志 名为 job_router 和 job_router_instance_runners。默认禁用。

获取 Runner 的 Job Router 发现信息。

先决条件：

• 您必须提供有效的 Runner 认证令牌。

plaintext
GET /runners/router/discovery

shell
curl --header "Runner-Token: <runner_authentication_token>" \
     --url "https://gitlab.example.com/api/v4/runners/router/discovery"

响应：

响应包含以下字段：

响应返回以下状态码之一：

示例响应：

json
{
    "server_url": "wss://kas.example.com"
}