Skip to content

帮
帮助文档

GitCode / 帮助文档

通知 1562
Star 123
Fork 139
帮
帮助文档

runners

最后修改来自于BaiXuePrincess
页面历史

Runners API

注册和验证令牌

将 Runner 与 GitCode 连接时需要以下两个令牌(token)

令牌 描述
注册令牌 用于注册 Runner 的令牌. 可以通过 GitCode 获得
认证令牌 用于对 Runner 进行身份验证的令牌. 它可以在注册 Runner 时自动获得，也可以通过 Runners API 手动注册时获得

以下是在 Runner 注册中如何使用两个令牌的示例：

  1. 您使用注册令牌通过 API 注册了 Runner，并返回了认证令牌

  2. 您使用该认证令牌并将其添加到 Runner 的配置文件中：

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

然后将 GitCode 和 Runner 连接起来。

已拥有的 runners 列表

获取可供用户使用的特定 runners 的列表。

GET /runners
GET /runners?scope=active
GET /runners?type=project_type
GET /runners?status=active
GET /runners?tag_list=tag1,tag2
属性 类型 必需的 描述
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 的标签列表 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/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"
	}
]

获取 runner 详情

获取 runner 的详细信息，只有在当前项目或组织中至少拥有Maintainer权限的用户才可以获取 runner 的详情。

GET /runners/:id
属性 类型 必需的 描述
id integer 是 runner ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/runners/6"

**注意：**响应中的token属性在 GitLab 12.10中已弃用. 并在GitLab 13.0 中删除.

响应示例：

{
    "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 的详细信息。

PUT /runners/:id
属性 类型 必需的 描述
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 处理作业的最大超时时间 
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"

响应示例：

{
    "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 。

PUT --form "active=false"  /runners/:runner_id
属性 类型 必需的 描述
id integer 是 runner ID

获取 runner 中的流水线任务列表

列出正在处理或由指定 runner 处理的作业。

GET /runners/:id/jobs
属性 类型 必需的 描述
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://gitcode.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"
        }
    }
]

获取项目的 runner 列表

列出项目中所有可用的 runner （特定的和共享的），如果定义了至少一个共享 runner，则列出共享 runner。

GET /projects/:id/runners
GET /projects/:id/runners?scope=active
GET /projects/:id/runners?type=project_type
GET /projects/:id/runners?status=active
GET /projects/:id/runners?tag_list=tag1,tag2
属性 类型 必需的 描述
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://gitcode.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"
    }
]

在项目中启用一个 runner

在项目中启用可用的特定 runner 。

POST /projects/:id/runners
属性 类型 必需的 描述
id integer/string 是 经过身份验证的用户拥有的项目的 ID 或项目的 URL Path
runner_id integer 是 runner ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.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"
}

在项目中禁用某一个 runner

禁用项目中的特定 runner，仅当该项目不是与指定 runner 关联的唯一项目时，它才有效；否则返回错误，请改用 删除 runner命令。

DELETE /projects/:id/runners/:runner_id
属性 类型 必需的 描述
id integer/string 是 经过身份验证的用户拥有的项目的 ID 或项目的 URL Path
runner_id integer 是 runner ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/projects/9/runners/9"

获取组织中的 runner 列表

列出组中的所有 runner （特定的和共享的）以及其父组织，如果定义了至少一个共享 runner，则列出共享 runner。

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
属性 类型 必需的 描述
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://gitcode.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"
  }
]

注册一个 runner

为该实例注册一个新的运行器。

POST /runners
属性 类型 必需的 描述
token string 是 Registration token.
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://gitcode.net/api/v4/runners" --form "token=<registration_token>" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2"

响应:

状态码 描述
201 runner 已创建

响应示例：

{
    "id": 12345,
    "token": "6337ff461c94fd3fa32ba3b1ff4125"
}

删除某个 runner

可以通过以下两种方式删除某个已注册的 runner：

  • 通过指定 runner ID 删除
  • 通过指定 runner 的认证令牌删除

通过 runner ID 删除

要按 ID 删除 runner，请使用你的访问令牌和 runner ID 进行删除：

DELETE /runners/:id
属性 类型 必需的 描述
id integer 是 runner 的ID。在项目设置 > CI/CD下展开 Runners后可见，在 Remove Runner 按钮下方，是一个以 #号 开头的 ID，例如，#6。 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitcode.net/api/v4/runners/6"

通过认证令牌删除 runner

使用认证令牌删除某个 runner

DELETE /runners
属性 类型 必需的 描述
token string 是 runner 的认证令牌 
curl --request DELETE "https://gitcode.net/api/v4/runners" \
     --form "token=<authentication_token>"

相应:

状态码 描述
204 runner 已被删除

验证 runner 的认证令牌

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

POST /runners/verify
属性 类型 必需的 描述
token string 是 runner 的认证令牌 
curl --request POST "https://gitcode.net/api/v4/runners/verify" --form "token=<authentication_token>"

响应:

状态码 描述
200 凭证有效
403 凭证无效