自托管运行器组
自托管运行器组 API 允许您管理自托运行器组。
关于自托管运行器组 API
自托管运行器组 API 允许您管理自托管运行器组。 更多信息请参阅“使用组管理对自托管运行器的访问”。
此 API 适用于经过身份验证的用户、OAuth 应用程序 和 GitHub 应用程序。 访问令牌需要 repo 作用域（对于私有仓库）和 public_repo 作用域（对于内部仓库）。 GitHub 应用程序 必须对仓库具有管理权限，或者对组织具有 organization_self_hosted_runners 权限。 经过身份验证的用户必须具有对存储库或组织的管理员访问权限或者企业的 manage_runners:enterprise 作用域才能使用此 API。
List self-hosted runner groups for an enterprise
Lists all self-hosted runner groups for an enterprise.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
| 查询参数 |
| 名称, 类型, 描述 |
per_pageintegerThe number of results per page (max 100). 默认值: |
pageintegerPage number of the results to fetch. 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groupsResponse
Status: 200{
"total_count": 3,
"runner_groups": [
{
"id": 1,
"name": "Default",
"visibility": "all",
"default": true,
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/1/runners",
"allows_public_repositories": false
},
{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/2/runners",
"allows_public_repositories": true
},
{
"id": 3,
"name": "expensive-hardware",
"visibility": "private",
"default": false,
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner_groups/3/runners",
"allows_public_repositories": true
}
]
}Create a self-hosted runner group for an enterprise
Creates a new self-hosted runner group for an enterprise.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
| 正文参数 |
| 名称, 类型, 描述 |
namestring必选Name of the runner group. |
visibilitystringVisibility of a runner group. You can select all organizations or select individual organization. 可以是以下其中之一: |
selected_organization_idsarray of integersList of organization IDs that can access the runner group. |
runnersarray of integersList of runner IDs to add to the runner group. |
allows_public_repositoriesbooleanWhether the runner group can be used by 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
201 | Created |
代码示例
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups \
-d '{"name":"Expensive hardware runners","visibility":"selected","selected_organization_ids":[32,91],"runners":[9,2]}'Response
Status: 201{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": false
}Get a self-hosted runner group for an enterprise
Gets a specific self-hosted runner group for an enterprise.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_IDResponse
Status: 200{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": false
}Update a self-hosted runner group for an enterprise
Updates the name and visibility of a self-hosted runner group in an enterprise.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
| 正文参数 |
| 名称, 类型, 描述 |
namestringName of the runner group. |
visibilitystringVisibility of a runner group. You can select all organizations or select individual organizations. 默认值: 可以是以下其中之一: |
allows_public_repositoriesbooleanWhether the runner group can be used by 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID \
-d '{"name":"Expensive hardware runners","visibility":"selected"}'Response
Status: 200{
"id": 2,
"name": "Expensive hardware runners",
"visibility": "selected",
"default": false,
"selected_organizations_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/organizations",
"runners_url": "https://api.github.com/enterprises/octo-corp/actions/runner-groups/2/runners",
"allows_public_repositories": true
}Delete a self-hosted runner group from an enterprise
Deletes a self-hosted runner group for an enterprise.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_IDResponse
Status: 204List self-hosted runners in a group for an enterprise
Lists the self-hosted runners that are in a specific enterprise group.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
| 查询参数 |
| 名称, 类型, 描述 |
per_pageintegerThe number of results per page (max 100). 默认值: |
pageintegerPage number of the results to fetch. 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runnersResponse
Status: 200{
"total_count": 2,
"runners": [
{
"id": 23,
"name": "linux_runner",
"os": "linux",
"status": "online",
"busy": true,
"labels": [
{
"id": 5,
"name": "self-hosted",
"type": "read-only"
},
{
"id": 7,
"name": "X64",
"type": "read-only"
},
{
"id": 11,
"name": "Linux",
"type": "read-only"
}
]
},
{
"id": 24,
"name": "mac_runner",
"os": "macos",
"status": "offline",
"busy": false,
"labels": [
{
"id": 5,
"name": "self-hosted",
"type": "read-only"
},
{
"id": 7,
"name": "X64",
"type": "read-only"
},
{
"id": 20,
"name": "macOS",
"type": "read-only"
},
{
"id": 21,
"name": "no-gpu",
"type": "custom"
}
]
}
]
}Set self-hosted runners in a group for an enterprise
Replaces the list of self-hosted runners that are part of an enterprise runner group.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
| 正文参数 |
| 名称, 类型, 描述 |
runnersarray of integers必选List of runner IDs to add to the runner group. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners \
-d '{"runners":[9,2]}'Response
Status: 204Add a self-hosted runner to a group for an enterprise
Adds a self-hosted runner to a runner group configured in an enterprise.
You must authenticate using an access token with the manage_runners:enterprise
scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
runner_idinteger必选Unique identifier of the self-hosted runner. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_IDResponse
Status: 204Remove a self-hosted runner from a group for an enterprise
Removes a self-hosted runner from a group configured in an enterprise. The runner is then returned to the default group.
You must authenticate using an access token with the manage_runners:enterprise scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
enterprisestring必选The slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
runner_idinteger必选Unique identifier of the self-hosted runner. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_IDResponse
Status: 204List self-hosted runner groups for an organization
Lists all self-hosted runner groups configured in an organization and inherited from an enterprise.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
| 查询参数 |
| 名称, 类型, 描述 |
per_pageintegerThe number of results per page (max 100). 默认值: |
pageintegerPage number of the results to fetch. 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groupsResponse
Status: 200{
"total_count": 3,
"runner_groups": [
{
"id": 1,
"name": "Default",
"visibility": "all",
"default": true,
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/1/runners",
"inherited": false,
"allows_public_repositories": true
},
{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_repositories_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/repositories",
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/runners",
"inherited": true,
"allows_public_repositories": true
},
{
"id": 3,
"name": "expensive-hardware",
"visibility": "private",
"default": false,
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/3/runners",
"inherited": false,
"allows_public_repositories": true
}
]
}Create a self-hosted runner group for an organization
The self-hosted runner groups REST API is available with GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see "GitHub's products."
Creates a new self-hosted runner group for an organization.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
| 正文参数 |
| 名称, 类型, 描述 |
namestring必选Name of the runner group. |
visibilitystringVisibility of a runner group. You can select all repositories, select individual repositories, or limit access to private repositories. 默认值: 可以是以下其中之一: |
selected_repository_idsarray of integersList of repository IDs that can access the runner group. |
runnersarray of integersList of runner IDs to add to the runner group. |
allows_public_repositoriesbooleanWhether the runner group can be used by 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
201 | Created |
代码示例
curl \
-X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups \
-d '{"name":"Expensive hardware runners","visibility":"selected","selected_repository_ids":[32,91],"runners":[9,2]}'Response
Status: 201{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_repositories_url": "https://api.github.com/orgs/octo-org/actions/runner-groups/2/repositories",
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/runners",
"inherited": false,
"allows_public_repositories": true
}Get a self-hosted runner group for an organization
Gets a specific self-hosted runner group for an organization.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_IDResponse
Status: 200{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_repositories_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/repositories",
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/runners",
"inherited": false,
"allows_public_repositories": true
}Update a self-hosted runner group for an organization
The self-hosted runner groups REST API is available with GitHub Enterprise Cloud. For more information, see "GitHub's products."
Updates the name and visibility of a self-hosted runner group in an organization.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
| 正文参数 |
| 名称, 类型, 描述 |
namestring必选Name of the runner group. |
visibilitystringVisibility of a runner group. You can select all repositories, select individual repositories, or all private repositories. 可以是以下其中之一: |
allows_public_repositoriesbooleanWhether the runner group can be used by 默认值: |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
200 | OK |
代码示例
curl \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_ID \
-d '{"name":"Expensive hardware runners","visibility":"selected"}'Response
Status: 200{
"id": 2,
"name": "octo-runner-group",
"visibility": "selected",
"default": false,
"selected_repositories_url": "https://api.github.com/orgs/octo-org/actions/runner-groups/2/repositories",
"runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/runners",
"inherited": false,
"allows_public_repositories": true
}Delete a self-hosted runner group from an organization
Deletes a self-hosted runner group for an organization.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_IDResponse
Status: 204Add a self-hosted runner to a group for an organization
Adds a self-hosted runner to a runner group configured in an organization.
You must authenticate using an access token with the admin:org scope to use this endpoint.
参数
| 标头 |
|---|
| 名称, 类型, 描述 |
acceptstringSetting to |
| 路径参数 |
| 名称, 类型, 描述 |
orgstring必选The organization name. The name is not case sensitive. |
runner_group_idinteger必选Unique identifier of the self-hosted runner group. |
runner_idinteger必选Unique identifier of the self-hosted runner. |
HTTP 响应状态代码
| 状态代码 | 描述 |
|---|---|
204 | No Content |
代码示例
curl \
-X PUT \
-H "Accept: application/vnd.github+json" \
-H "Authorization: token <TOKEN>" \
https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_IDResponse
Status: 204