Runners API · Gitlab 中文文檔

# Runners API > 原文：[https://docs.gitlab.com/ee/api/runners.html](https://docs.gitlab.com/ee/api/runners.html) * [Registration and authentication tokens](#registration-and-authentication-tokens) * [List owned runners](#list-owned-runners) * [List all runners](#list-all-runners) * [Get runner’s details](#get-runners-details) * [Update runner’s details](#update-runners-details) * [Remove a runner](#remove-a-runner) * [List runner’s jobs](#list-runners-jobs) * [List project’s runners](#list-projects-runners) * [Enable a runner in project](#enable-a-runner-in-project) * [Disable a runner from project](#disable-a-runner-from-project) * [List group’s runners](#list-groups-runners) * [Register a new Runner](#register-a-new-runner) * [Delete a registered Runner](#delete-a-registered-runner) * [Verify authentication for a registered Runner](#verify-authentication-for-a-registered-runner) # Runners API[](#runners-api "Permalink") 在 GitLab 8.5 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/2640) ## Registration and authentication tokens[](#registration-and-authentication-tokens "Permalink") 將 Runner 與 GitLab 連接時要考慮兩個標記. | Token | Description | | --- | --- | | 注冊令牌 | 用于[注冊 Runner 的](https://docs.gitlab.com/runner/register/)令牌. 可以[通過 GitLab 獲得](../ci/runners/README.html) . | | 認證令牌 | 用于通過 GitLab 實例對 Runner 進行身份驗證的令牌. 它可以在[注冊 Runner](https://docs.gitlab.com/runner/register/)時自動獲得，也可以[通過 Runners API](#register-a-new-runner)手動[注冊時獲得](#register-a-new-runner) . | 這是在 Runner 注冊中如何使用兩個令牌的示例： 1. 您使用注冊令牌通過 GitLab API 注冊了 Runner，并返回了身份驗證令牌. 2. 您使用該身份驗證令牌并將其添加到[Runner 的配置文件中](https://docs.gitlab.com/runner/commands/) ： ``` [[runners]] token = "<authentication_token>" ``` 然后將 GitLab 和 Runner 連接起來. ## List owned runners[](#list-owned-runners "Permalink") 獲取可供用戶使用的特定跑步者的列表. ``` GET /runners GET /runners?scope=active GET /runners?type=project_type GET /runners?status=active GET /runners?tag_list=tag1,tag2 ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `scope` | string | no | Deprecated: Use `type` or `status` instead. The scope of specific runners to show, one of: `active`, `paused`, `online`, `offline`; showing all runners if none provided | | `type` | string | no | 要顯示的跑步者的類型，其中之一： `instance_type` ， `group_type` ， `project_type` | | `status` | string | no | 要顯示的跑步者狀態，其中之一： `active` ， `paused` ， `online` ， `offline` | | `tag_list` | 字符串數組 | no | 跑步者標簽列表 | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/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" } ] ``` ## List all runners[](#list-all-runners "Permalink") 獲取 GitLab 實例中所有跑步者的列表（特定的和共享的）. 訪問僅限于具有`admin`權限的用戶. ``` GET /runners/all GET /runners/all?scope=online GET /runners/all?type=project_type GET /runners/all?status=active GET /runners/all?tag_list=tag1,tag2 ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `scope` | string | no | 不推薦使用：改為使用`type`或`status` . 參與者顯示的范圍，其中之一： `specific` ， `shared` ， `active` ，已`paused` ， `online` ， `offline` ；顯示所有跑步者（如果未提供） | | `type` | string | no | 要顯示的跑步者的類型，其中之一： `instance_type` ， `group_type` ， `project_type` | | `status` | string | no | 要顯示的跑步者狀態，其中之一： `active` ， `paused` ， `online` ， `offline` | | `tag_list` | 字符串數組 | no | 跑步者標簽列表 | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/all" ``` 響應示例： ``` [ { "active": true, "description": "shared-runner-1", "id": 1, "ip_address": "127.0.0.1", "is_shared": true, "name": null, "online": true, "status": "online" }, { "active": true, "description": "shared-runner-2", "id": 3, "ip_address": "127.0.0.1", "is_shared": true, "name": null, "online": false "status": "offline" }, { "active": true, "description": "test-1-20150125", "id": 6, "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": true "status": "paused" }, { "active": true, "description": "test-2-20150125", "id": 8, "ip_address": "127.0.0.1", "is_shared": false, "name": null, "online": false, "status": "offline" } ] ``` ## Get runner’s details[](#get-runners-details "Permalink") 獲取跑步者的詳細信息. ``` GET /runners/:id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | 跑步者 ID | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` **注意：**響應中的`token`屬性[在 GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320)中已棄用. 并在[GitLab 13.0 中](https://gitlab.com/gitlab-org/gitlab/-/issues/214322)刪除. 響應示例： ``` { "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 } ``` ## Update runner’s details[](#update-runners-details "Permalink") 更新跑步者的詳細信息. ``` PUT /runners/:id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | 跑步者 ID | | `description` | string | no | 跑步者 | | `active` | boolean | no | 跑步者的狀態；可以設置為`true`或`false` | | `tag_list` | array | no | 跑步者的標簽列表；放置標簽數組，這些標簽應最終分配給跑步者 | | `run_untagged` | boolean | no | 指示跑步者可以執行未加標簽的作業的標志 | | `locked` | boolean | no | 指示跑步者被鎖定的標志 | | `access_level` | string | no | 跑步者的 access_level; `not_protected`或`ref_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" ``` **注意：**響應中的`token`屬性[在 GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/issues/214320)中已棄用. 并在[GitLab 13.0 中](https://gitlab.com/gitlab-org/gitlab/-/issues/214322)刪除. 響應示例： ``` { "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 } ``` ## Remove a runner[](#remove-a-runner "Permalink") 卸下流道. ``` DELETE /runners/:id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | The ID of a runner | ``` curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/runners/6" ``` ## List runner’s jobs[](#list-runners-jobs "Permalink") 在 GitLab 10.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15432) . 列出正在處理或由指定運行程序處理的作業. ``` GET /runners/:id/jobs ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | 跑步者 ID | | `status` | string | no | 工作狀態；其中之一： `running` ， `success` ， `failed` ， `canceled` | | `order_by` | string | no | 按`id`訂購工作. | | `sort` | string | no | 按`asc`或`desc`順序對作業進行排序（默認值： `desc` ） | ``` 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" } } ] ``` ## List project’s runners[](#list-projects-runners "Permalink") List all runners (specific and shared) available in the project. 列出項目中所有可用的跑步者（特定的和共享的）. Shared runners are listed if at least one shared runner is defined. 如果定義了至少一個共享運行程序，則列出共享運行程序. ``` 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 ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `scope` | string | no | 不推薦使用：改為使用`type`或`status` . 要顯示的特定跑步者的范圍，其中之一： `active` ， `paused` ， `online` ， `offline` ；顯示所有跑步者（如果未提供） | | `type` | string | no | 要顯示的跑步者的類型，其中之一： `instance_type` ， `group_type` ， `project_type` | | `status` | string | no | 要顯示的跑步者狀態，其中之一： `active` ， `paused` ， `online` ， `offline` | | `tag_list` | 字符串數組 | no | 跑步者標簽列表 | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/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" } ] ``` ## Enable a runner in project[](#enable-a-runner-in-project "Permalink") 在項目中啟用可用的特定運行器. ``` POST /projects/:id/runners ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `runner_id` | integer | yes | 跑步者 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, "name": null, "online": true, "status": "online" } ``` ## Disable a runner from project[](#disable-a-runner-from-project "Permalink") 禁用項目中的特定運行器. 僅當該項目不是與指定運行器關聯的唯一項目時，它才有效. 如果是這樣，則返回錯誤. 改用" [刪除亞軍"](#remove-a-runner)電話. ``` DELETE /projects/:id/runners/:runner_id ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer/string | yes | 經過身份驗證的用戶擁有[的項目](README.html#namespaced-path-encoding)的 ID 或[URL 編碼路徑](README.html#namespaced-path-encoding) | | `runner_id` | integer | yes | 跑步者 ID | ``` curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/9/runners/9" ``` ## List group’s runners[](#list-groups-runners "Permalink") 列出組中的所有跑步者（特定的和共享的）以及其祖先組. 如果定義了至少一個共享運行程序，則列出共享運行程序. ``` 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 ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `id` | integer | yes | 認證用戶擁有的組的 ID | | `type` | string | no | 要顯示的跑步者的類型，其中之一： `instance_type` ， `group_type` ， `project_type` | | `status` | string | no | 要顯示的跑步者狀態，其中之一： `active` ， `paused` ， `online` ， `offline` | | `tag_list` | 字符串數組 | no | 跑步者標簽列表 | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/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" } ] ``` ## Register a new Runner[](#register-a-new-runner "Permalink") 為該實例注冊一個新的運行器. ``` POST /runners ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `token` | string | yes | [Registration token](#registration-and-authentication-tokens). | | `description` | string | no | 跑步者的描述 | | `info` | hash | no | 跑步者的元數據 | | `active` | boolean | no | 跑步者是否活躍 | | `locked` | boolean | no | Runner 是否應該為當前項目鎖定 | | `run_untagged` | boolean | no | 跑步者是否應處理未加標簽的工作 | | `tag_list` | 字符串數組 | no | 跑步者標簽列表 | | `access_level` | string | no | 跑步者的 access_level; `not_protected`或`ref_protected` | | `maximum_timeout` | integer | no | 此 Runner 處理作業的最大超時時間 | ``` 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" ``` Response: | Status | Description | | --- | --- | | 201 | 跑步者已創建 | 響應示例： ``` { "id": "12345", "token": "6337ff461c94fd3fa32ba3b1ff4125" } ``` ## Delete a registered Runner[](#delete-a-registered-runner "Permalink") 刪除注冊的跑步者. ``` DELETE /runners ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `token` | string | yes | Runner’s [authentication token](#registration-and-authentication-tokens). | ``` curl --request DELETE "https://gitlab.example.com/api/v4/runners" --form "token=<authentication_token>" ``` Response: | Status | Description | | --- | --- | | 204 | 跑步者已被刪除 | ## Verify authentication for a registered Runner[](#verify-authentication-for-a-registered-runner "Permalink") 驗證注冊的運行程序的身份驗證憑據. ``` POST /runners/verify ``` | Attribute | Type | Required | Description | | --- | --- | --- | --- | | `token` | string | yes | Runner’s [authentication token](#registration-and-authentication-tokens). | ``` curl --request POST "https://gitlab.example.com/api/v4/runners/verify" --form "token=<authentication_token>" ``` Response: | Status | Description | | --- | --- | | 200 | 憑證有效 | | 403 | 憑證無效 |