Runners API

本文档描述了注册到实例的 runner 的端点。要创建与当前用户链接的 runner，请参阅创建 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 列表。

先决条件：

• 您必须是目标命名空间或项目的管理员或具有所有者角色。
• 对于 instance_type，您必须是极狐GitLab实例的管理员。

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>" "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    },
14    {
15        "active": true,
16        "paused": false,
17        "description": "test-2-20150125",
18        "id": 8,
19        "ip_address": "",
20        "is_shared": false,
21        "runner_type": "group_type",
22        "name": null,
23        "online": false,
24        "status": "offline"
25    }
26]

列出所有 runner#

获取极狐GitLab实例中所有 runner 的列表（项目和共享）。访问权限仅限于具有管理员访问权限的用户。

先决条件：

• 您必须是目标命名空间或项目的管理员或具有所有者角色。
• 对于 instance_type，您必须是极狐GitLab实例的管理员。

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>" "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    },
14    {
15        "active": true,
16        "paused": false,
17        "description": "shared-runner-2",
18        "id": 3,
19        "ip_address": "",
20        "is_shared": true,
21        "runner_type": "instance_type",
22        "name": null,
23        "online": false,
24        "status": "offline"
25    },
26    {
27        "active": true,
28        "paused": false,
29        "description": "test-1-20150125",
30        "id": 6,
31        "ip_address": "",
32        "is_shared": false,
33        "runner_type": "project_type",
34        "name": null,
35        "online": true,
36        "status": "paused"
37    },
38    {
39        "active": true,
40        "paused": false,
41        "description": "test-2-20150125",
42        "id": 8,
43        "ip_address": "",
44        "is_shared": false,
45        "runner_type": "group_type",
46        "name": null,
47        "online": false,
48        "status": "offline"
49    }
50]

要查看超过前 20 个 runner，请使用分页。

获取 runner 的详细信息#

获取 runner 的详细信息。

通过此端点的实例 runner 详细信息对所有经过身份验证的用户可用。

先决条件：

• 您必须至少拥有目标命名空间或项目的开发者角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
GET /runners/:id

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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    "platform": null,
16    "projects": [
17        {
18            "id": 1,
19            "name": "GitLab Community Edition",
20            "name_with_namespace": "GitLab.org / GitLab Community Edition",
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    ],
30    "version": null,
31    "access_level": "ref_protected",
32    "maximum_timeout": 3600
33}

更新 runner 的详细信息#

更新 runner 的详细信息。

plaintext
PUT /runners/:id

先决条件：

• 对于 instance_type，您必须是极狐GitLab实例的管理员。
• 对于 group_type，您必须拥有目标命名空间的所有者角色。
• 对于 project_type，您必须至少拥有目标项目的维护者角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

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

示例响应：

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    "platform": null,
15    "projects": [
16        {
17            "id": 1,
18            "name": "GitLab Community Edition",
19            "name_with_namespace": "GitLab.org / GitLab Community Edition",
20            "path": "gitlab-foss",
21            "path_with_namespace": "gitlab-org/gitlab-foss"
22        }
23    ],
24    "revision": null,
25    "tag_list": [
26        "ruby",
27        "mysql",
28        "tag1",
29        "tag2"
30    ],
31    "version": null,
32    "access_level": "ref_protected",
33    "maximum_timeout": null
34}

暂停 runner#

暂停 runner。

先决条件：

• 对于 instance_type，您必须是极狐GitLab实例的管理员。
• 对于 group_type，您必须拥有目标命名空间的所有者角色。
• 对于 project_type，您必须至少拥有目标项目的维护者角色。
• 具有 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 --header "PRIVATE-TOKEN: <your_access_token>" \
2     --form "paused=true"  "https://gitlab.example.com/api/v4/runners/6"
3
4# --或--
5
6# 已弃用：计划在 16.0 中删除
7curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
8     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"

列出由 runner 处理的作业#

列出指定 runner 正在处理或已处理的作业。作业列表仅限于用户在其中至少拥有报告者角色的项目。

plaintext
GET /runners/:id/jobs

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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            "skype": "",
27            "linkedin": "",
28            "twitter": "",
29            "website_url": "",
30            "organization": null
31        },
32        "commit": {
33            "id": "97de212e80737a608d939f648d959671fb0a0142",
34            "short_id": "97de212e",
35            "title": "Update configuration\r",
36            "created_at": "2017-11-16T08:50:28.000Z",
37            "parent_ids": [
38                "1b12f15a11fc6e62177bef08f47bc7b5ce50b141",
39                "498214de67004b1da3d820901307bed2a68a8ef6"
40            ],
41            "message": "See merge request !123",
42            "author_name": "John Doe2",
43            "author_email": "user2@example.org",
44            "authored_date": "2017-11-16T08:50:27.000Z",
45            "committer_name": "John Doe2",
46            "committer_email": "user2@example.org",
47            "committed_date": "2017-11-16T08:50:27.000Z"
48        },
49        "pipeline": {
50            "id": 2,
51            "sha": "97de212e80737a608d939f648d959671fb0a0142",
52            "ref": "main",
53            "status": "running"
54        },
55        "project": {
56            "id": 1,
57            "description": null,
58            "name": "project1",
59            "name_with_namespace": "John Doe2 / project1",
60            "path": "project1",
61            "path_with_namespace": "namespace1/project1",
62            "created_at": "2017-11-16T18:38:46.620Z"
63        }
64    }
65]

列出 runner 的管理器#

列出 runner 的所有管理器。

plaintext
GET /runners/:id/managers

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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    },
14    {
15        "id": 2,
16        "system_id": "runner-2",
17        "version": "16.11.0",
18        "revision": "91a27b2a",
19        "platform": "linux",
20        "architecture": "amd64",
21        "created_at": "2024-06-09T09:12:02.507Z",
22      "contacted_at": "2024-06-09T06:30:09.355Z",
23        "ip_address": "127.0.0.1",
24        "status": "offline",
25
26    }
27]

列出项目的 runner#

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

先决条件：

• 您必须是目标项目的管理员或至少拥有维护者角色。

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

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "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    },
14    {
15        "active": true,
16        "paused": false,
17        "description": "development_runner",
18        "id": 5,
19        "ip_address": "",
20        "is_shared": true,
21        "runner_type": "instance_type",
22        "name": null,
23        "online": true,
24        "status": "online"
25    }
26]

将 runner 分配给项目#

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

先决条件：

• 对于 instance_type，您必须是极狐GitLab实例的管理员。
• 对于 group_type，您必须拥有目标命名空间的所有者角色。
• 对于 project_type，您必须至少拥有目标项目的维护者角色。

plaintext
POST /projects/:id/runners

shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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}

从项目中取消分配 runner#

从项目中取消分配项目 runner。您无法从拥有者项目中取消分配 runner。如果尝试此操作，则会发生错误。请改用调用删除 runner。

先决条件：

• 对于 instance_type，您必须是极狐GitLab实例的管理员。
• 对于 group_type，您必须拥有目标命名空间的所有者角色。
• 对于 project_type，您必须至少拥有目标项目的维护者角色。

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

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

列出群组的 runner#

列出群组及其祖先群组中可用的所有 runner，包括任何允许的实例 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>" "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  },
14  {
15    "id": 6,
16    "description": "Test",
17    "ip_address": "",
18    "active": true,
19    "paused": false,
20    "is_shared": true,
21    "runner_type": "instance_type",
22    "name": "gitlab-runner",
23    "online": false,
24    "status": "offline"
25  },
26  {
27    "id": 8,
28    "description": "Test 2",
29    "ip_address": "",
30    "active": true,
31    "paused": false,
32    "is_shared": false,
33    "runner_type": "group_type",
34    "name": "gitlab-runner",
35    "online": null,
36    "status": "never_contacted"
37  }
38]

创建 runner#

使用 runner 注册令牌创建 runner。

plaintext
POST /runners

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

响应：

示例响应：

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：

先决条件：

• 对于 instance_type，您必须是极狐GitLab实例的管理员。
• 对于 group_type，您必须拥有目标命名空间的所有者角色。
• 对于 project_type，您必须至少拥有目标项目的维护者角色。
• 具有 manage_runner 范围和适当角色的访问令牌。

plaintext
DELETE /runners/:id

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

通过身份验证令牌删除 runner#

要通过使用 runner 的身份验证令牌删除 runner：

先决条件：

• 您必须是目标命名空间或项目的管理员或拥有所有者角色。
• 对于 instance_type，您必须是极狐GitLab实例的管理员。

plaintext
DELETE /runners

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

响应：

验证已注册 runner 的身份验证#

验证已注册 runner 的身份验证凭证。

plaintext
POST /runners/verify

shell
curl --request POST "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>" \
     "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>" \
     "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>" \
     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"

通过使用 runner ID 重置 runner 的认证令牌#

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

先决条件：

1. 对于 instance_type，您必须是极狐GitLab 实例的管理员。
2. 对于 group_type，您必须拥有目标命名空间的所有者角色。
3. 对于 project_type，您必须至少拥有目标项目的维护者角色。
4. 一个具有 manage_runner 范围和适当角色的访问令牌。

plaintext
POST /runners/:id/reset_authentication_token

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

Example response:

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>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

Example response:

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