Skip to main content
ドキュメントへの更新が頻繁に発行されており、このページの翻訳はまだ行われている場合があります。 最新の情報については、「英語のドキュメント」を参照してください。
現在、GitHub AE は限定的リリースです。

セルフホストランナーグループ

この REST API を使って、GitHub Actions のセルフホステッド ランナー グループを操作します。

GitHub Actions のセルフホステッド ランナー グループについて

この REST API を使うと、GitHub Actions のセルフホステッド ランナーのグループを管理できます。 詳細については、「グループを使用してセルフホスト ランナーへのアクセスを管理する」を参照してください。

このエンドポイントは、認証されたユーザー、OAuth Apps、GitHub Apps で使用できます。 アクセス トークンには、プライベート リポジトリの repo スコープと内部リポジトリの public_repo スコープが必要です。 GitHub Apps には、リポジトリの administration アクセス許可、または Organization の organization_self_hosted_runners アクセス許可が必要です。 認証されたユーザーがこれらのエンドポイントを使うには、リポジトリまたは組織への管理者アクセス、または企業の manage_runners:enterprise スコープが必要です。

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
enterprisestring必須

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

クエリ パラメーター
名前, Type, 説明
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

get/enterprises/{enterprise}/actions/runner-groups
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups

Response

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
enterprisestring必須

The slug version of the enterprise name. You can also substitute this value with the enterprise id.

本文のパラメーター
名前, Type, 説明
namestring必須

Name of the runner group.

visibilitystring

Visibility of a runner group. You can select all organizations or select individual organization.

次のいずれかにできます: selected, all

selected_organization_idsarray of integers

List of organization IDs that can access the runner group.

runnersarray of integers

List of runner IDs to add to the runner group.

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP 応答状態コード

状態コード説明
201

Created

コード サンプル

post/enterprises/{enterprise}/actions/runner-groups
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

get/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID

Response

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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.

本文のパラメーター
名前, Type, 説明
namestring

Name of the runner group.

visibilitystring

Visibility of a runner group. You can select all organizations or select individual organizations.

Default: all

次のいずれかにできます: selected, all

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

patch/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
curl \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

delete/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID

Response

Status: 204

List 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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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.

クエリ パラメーター
名前, Type, 説明
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

get/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners

Response

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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.

本文のパラメーター
名前, Type, 説明
runnersarray of integers必須

List of runner IDs to add to the runner group.

HTTP 応答状態コード

状態コード説明
204

No Content

コード サンプル

put/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners
curl \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners \ -d '{"runners":[9,2]}'

Response

Status: 204

Add 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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

put/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}
curl \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_ID

Response

Status: 204

Remove 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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

delete/enterprises/{enterprise}/actions/runner-groups/{runner_group_id}/runners/{runner_id}
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/enterprises/ENTERPRISE/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_ID

Response

Status: 204

List self-hosted runner groups for an organization

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
orgstring必須

The organization name. The name is not case sensitive.

クエリ パラメーター
名前, Type, 説明
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

get/orgs/{org}/actions/runner-groups
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups

Response

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

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
orgstring必須

The organization name. The name is not case sensitive.

本文のパラメーター
名前, Type, 説明
namestring必須

Name of the runner group.

visibilitystring

Visibility of a runner group. You can select all repositories, select individual repositories, or limit access to private repositories.

Default: all

次のいずれかにできます: selected, all, private

selected_repository_idsarray of integers

List of repository IDs that can access the runner group.

runnersarray of integers

List of runner IDs to add to the runner group.

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP 応答状態コード

状態コード説明
201

Created

コード サンプル

post/orgs/{org}/actions/runner-groups
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-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

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
orgstring必須

The organization name. The name is not case sensitive.

runner_group_idinteger必須

Unique identifier of the self-hosted runner group.

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

get/orgs/{org}/actions/runner-groups/{runner_group_id}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_ID

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 }

Update a self-hosted runner group for an organization

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
orgstring必須

The organization name. The name is not case sensitive.

runner_group_idinteger必須

Unique identifier of the self-hosted runner group.

本文のパラメーター
名前, Type, 説明
namestring必須

Name of the runner group.

visibilitystring

Visibility of a runner group. You can select all repositories, select individual repositories, or all private repositories.

次のいずれかにできます: selected, all, private

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP 応答状態コード

状態コード説明
200

OK

コード サンプル

patch/orgs/{org}/actions/runner-groups/{runner_group_id}
curl \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-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

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

delete/orgs/{org}/actions/runner-groups/{runner_group_id}
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_ID

Response

Status: 204

Add a self-hosted runner to a group for an organization

に対応 GitHub Apps

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.

パラメーター

ヘッダー
名前, Type, 説明
acceptstring

Setting to application/vnd.github+json is recommended.

パス パラメーター
名前, Type, 説明
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

コード サンプル

put/orgs/{org}/actions/runner-groups/{runner_group_id}/runners/{runner_id}
curl \ -X PUT \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ https://HOSTNAME/api/v3/orgs/ORG/actions/runner-groups/RUNNER_GROUP_ID/runners/RUNNER_ID

Response

Status: 204