Runner API

引入于极狐GitLab 8.5。

注册和鉴权令牌

将 Runner 连接到极狐GitLab 时,需要考虑两个令牌。

令牌 描述
注册令牌 用于注册 Runner 的令牌。可以通过极狐GitLab 获取
鉴权令牌 用于使用极狐GitLab 实例对 Runner 进行鉴权的令牌。注册 Runner 或当手动注册 Runner 时通过 Runner API 或重置鉴权令牌时自动获取

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

  1. 您使用注册令牌通过极狐GitLab API 注册 Runner,以及返回鉴权令牌。
  2. 您使用该鉴权令牌并将其添加到 Runner 的配置文件

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

极狐GitLab 和 Runner 进行了连接。

列出拥有的 Runner

获取用户可用的特定 Runner 的列表。

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 已废弃:使用 typestatus。要显示的特定 Runner 的范围:activepausedonlineoffline。如未提供,则展示所有 Runner
type string no 要显示的 Runner 的类型:instance_typegroup_typeproject_type
status string no 要显示的 Runner 的状态:onlineofflinestalenever_contactedactivepaused 废弃于 14.8 并将移除于 16.0
paused boolean no 是否仅包括接收或忽略新作业的 Runner
tag_list string array no Runner 标签列表
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners"
notestatus 查询参数中的 activepaused 值废弃于 14.8,并将移除于 16.0。其被 paused查询参数代替。
note响应中的 active 参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

响应示例:

[
    {
        "active": true,
        "paused": false,
        "description": "test-1-20150125",
        "id": 6,
        "ip_address": "127.0.0.1",
        "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": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

列出所有 Runner

获取极狐GitLab 实例中所有 Runner 的列表(特定的和共享的)。仅具有管理员访问权限的用户可以访问。

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 已废弃:使用 typestatus。要显示的 Runner 的范围:specificsharedactivepausedonlineoffline。如未提供,则显示所有 Runner
type string no 要显示的 Runner 的类型:instance_typegroup_typeproject_type
status string no 要显示的 Runner 的状态:onlineofflinestalenever_contactedactivepaused 已废弃于 14.8,将移除于 16.0
paused boolean no 是否仅包含接受或忽略新作业的 Runner
tag_list string array no Runner 标签列表
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all"
notestatus 查询参数中的 activepaused 值已废弃于 14.8,并将移除于 16.0。被 paused 查询参数代替。
note响应中的 active 参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

响应示例:

[
    {
        "active": true,
        "paused": false,
        "description": "shared-runner-1",
        "id": 1,
        "ip_address": "127.0.0.1",
        "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": "127.0.0.1",
        "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": "127.0.0.1",
        "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": "127.0.0.1",
        "is_shared": false,
        "runner_type": "group_type",
        "name": null,
        "online": false,
        "status": "offline"
    }
]

要查看前 20 Runner 后的其他 Runner,请使用分页

获取 Runner 的详细信息

获取 Runner 的详细信息。

至少需要维护者角色才能在项目和群组级别获取 Runner 的详细信息。

通过此端点的实例级别的 Runner 的详细信息对所有登录用户可用。

GET /runners/:id
参数 类型 是否必需 描述
id integer yes Runner ID
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"
note响应中的 token 参数废弃于 12.10,并移除于 13.0。
note响应中的 active 参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

响应示例:

{
    "active": true,
    "paused": false,
    "architecture": null,
    "description": "test-1-20150125",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "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 yes Runner ID
description string no Runner 描述
active boolean no 已废弃:使用 :paused 代替。表明是否允许 Runner 接收作业的标记
paused boolean no 表明 Runner 是否应该忽略新作业的标记
tag_list array no Runner 标签列表。放置应该最终分配到 Runner 的标签
run_untagged boolean no 表明 Runner 可以执行未打标签的作业的标记
locked boolean no 表明 Runner 已锁定的标记
access_level string no Runner 的访问级别:not_protectedref_protected
maximum_timeout integer no Runner 处理作业时设置的最大的超时时间
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"
note响应中的 token 参数废弃于 12.10,并且移除于 13.0。
noteactive 查询参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

响应示例:

{
    "active": true,
    "architecture": null,
    "description": "test-1-20150125-test",
    "id": 6,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "group_type",
    "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 "paused=true" /runners/:runner_id

# --or--

# Deprecated: removal planned in 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"

# --or--

# Deprecated: removal planned in 16.0
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
     --form "active=false"  "https://gitlab.example.com/api/v4/runners/6"
noteactive 形式参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

列出 Runner 的作业

引入于极狐GitLab 10.3。

列出正在处理或已由指定 Runner 处理的作业。作业列表限制为用户至少具有报告者角色的项目。

GET /runners/:id/jobs
参数 类型 是否必需 描述
id integer yes Runner ID
status string no 作业状态:runningsuccessfailedcanceled
order_by string no 作业按照 id 进行排序
sort string no 按照 ascdesc 的顺序对作业进行排序(默认为 desc)。也指定 order_by,包括 id
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/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

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 已废弃:使用 typestatus 代替。要显示的特定 Runner 的范围:activepausedonlineoffline。如未提供,则显示所有 Runner
type string no 要显示的 Runner 的类型:instance_typegroup_typeproject_type
status string no 要显示的 Runner 的状态:onlineofflinestalenever_contactedactivepaused 已废弃于 14.8,并将移除于 16.0
paused boolean no 是否仅包含接受或拒绝新作业的 Runner
tag_list string array no Runner 标签列表
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners"
notestatus 查询参数中的 activepaused 值废弃于 14.8,并将移除于 16.0。被 paused 查询参数代替。
note响应中的 active 参数废弃于 14.8,并将移除于 16.0。被 paused 参数代替。

响应示例:

[
    {
        "active": true,
        "paused": false,
        "description": "test-2-20150125",
        "id": 8,
        "ip_address": "127.0.0.1",
        "is_shared": false,
        "runner_type": "project_type",
        "name": null,
        "online": false,
        "status": "offline"
    },
    {
        "active": true,
        "paused": false,
        "description": "development_runner",
        "id": 5,
        "ip_address": "127.0.0.1",
        "is_shared": true,
        "runner_type": "instance_type",
        "name": null,
        "online": true,
        "status": "online"
    }
]

在项目中启用 Runner

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

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"

响应示例:

{
    "active": true,
    "description": "test-2016-02-01",
    "id": 9,
    "ip_address": "127.0.0.1",
    "is_shared": false,
    "runner_type": "project_type",
    "name": null,
    "online": true,
    "status": "online"
}

在项目中禁用 Runner

在项目中禁用特定的 Runner。仅当项目不是与特定 Runner 关联的唯一项目时才可用。 这种情况下会返回错误。使用删除 Runner 的调用。

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_typegroup_typeproject_typeproject_type 废弃于 15.0
status string no 要显示的 Runner 的状态:onlineofflinestalenever_contactedactivepaused 废弃于 14.8,并将移除于 16.0
paused boolean no 是否仅包括创建或忽略新作业的 Runner
tag_list string array no Runner 的标签列表
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/9/runners"
notestatus 查询参数中的 activepaused 值废弃于 14.8,并将移除于 16.0。被 paused 查询参数代替。
note响应中的 active 参数废弃于 14.8,并将移除于 16.0。被 paused 参数替代。

响应示例:

[
  {
    "id": 3,
    "description": "Shared",
    "ip_address": "127.0.0.1",
    "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": "127.0.0.1",
    "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": "127.0.0.1",
    "active": true,
    "paused": false,
    "is_shared": false,
    "runner_type": "group_type",
    "name": "gitlab-runner",
    "online": null,
    "status": "never_contacted"
  }
]

注册新 Runner

为实例注册新 Runner。

POST /runners
参数 类型 是否必需 描述
token string yes 注册令牌
description string no Runner 描述
info hash no Runner 的元数据。可以包括 nameversionrevisionplatformarchitecture,但是在 UI 的管理中心中仅显示 version
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_protectedref_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

响应示例:

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

删除 Runner

删除 Runner 有两种方式:

  • 指定 Runner ID
  • 指定 Runner 的鉴权令牌

通过 ID 删除 Runner

要通过 ID 删除 Runner,请通过 Runner ID 使用您的访问令牌:

DELETE /runners/:id
参数 类型 是否必需 描述
id integer yes Runner ID。UI 中此 ID 在 设置 > CI/CD 下可见。展开 Runner,在 移除 Runner 按键下是 ID,ID 前面有 “#” 符号,例如 #6
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6"

通过鉴权令牌删除 Runner

使用鉴权令牌删除 Runner:

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 的鉴权令牌
curl --request POST "https://gitlab.example.com/api/v4/runners/verify" \
     --form "token=<authentication_token>"

响应:

状态 描述
200 证书有效
403 证书无效

重置实例的 Runner 注册令牌

引入于极狐GitLab 14.3。

为极狐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 注册令牌

引入于极狐GitLab 14.3。

为项目重置 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 注册令牌

引入于极狐GitLab 14.3。

为群组重置 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 的鉴权令牌。

POST /runners/:id/reset_authentication_token
参数 类型 是否必需 描述
id integer yes Runner ID
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/runners/1/reset_authentication_token"

响应示例:

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

使用当前令牌重置 Runner 的鉴权令牌

使用当前令牌的值作为输入重置 Runner 的鉴权令牌。

POST /runners/reset_authentication_token
参数 类型 是否必需 描述
token string yes Runner 的当前令牌
curl --request POST --form "token=<current token>" \
     "https://gitlab.example.com/api/v4/runners/reset_authentication_token"

响应示例:

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