{{< 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 的示例：

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

  2. 将身份验证令牌添加到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 的认证令牌。

先决条件：

  1. 对于 instance_type，您必须是极狐GitLab 实例的管理员。
  2. 对于 group_type，您必须拥有目标命名空间的所有者角色。
  3. 对于 project_type，您必须至少拥有目标项目的维护者角色。
  4. 一个具有 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"
}