Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
GitHub AE is currently under limited release.
 

 

Grupos de ejecutores auto-hospedados

La API de Grupos de Ejecutores Auto-Hospedados te permite administrar grupos para los ejecutores auto-hospedados.

Acerca de Self-hosted runner groups API

Self-hosted runners groups API te permite administrar grupos para los ejecutores autohospedados. Para más información, vea "Administración del acceso a ejecutores autohospedados mediante grupos".

Esta API se encuentra disponible para los usuarios autenticados, las OAuth Apps y las GitHub Apps. Los tokens de acceso necesitan el ámbito repo para los repositorios privados y el ámbito public_repo para los repositorios internos. GitHub Apps debe tener el permiso administration para los repositorios o el permiso organization_self_hosted_runners para las organizaciones. Los usuarios autenticados deben tener acceso administrativo a los repositorios u organizaciones, o bien el ámbito manage_runners:enterprise para empresas a fin de utilizar esta 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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

Query parameters
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes

Status codeDescription
200

OK

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

Body parameters
namestringRequired

Name of the runner group.

visibilitystring

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

Can be one of: 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 response status codes

Status codeDescription
201

Created

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

HTTP response status codes

Status codeDescription
200

OK

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

Body parameters
namestring

Name of the runner group.

visibilitystring

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

Default: all

Can be one of: selected, all

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP response status codes

Status codeDescription
200

OK

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

Query parameters
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes

Status codeDescription
200

OK

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

Body parameters
runnersarray of integersRequired

List of runner IDs to add to the runner group.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

runner_idintegerRequired

Unique identifier of the self-hosted runner.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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.

Parameters

Headers
acceptstring

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

Path parameters
enterprisestringRequired

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

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

runner_idintegerRequired

Unique identifier of the self-hosted runner.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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

Works with 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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

Query parameters
per_pageinteger

The number of results per page (max 100).

Default: 30

pageinteger

Page number of the results to fetch.

Default: 1

HTTP response status codes

Status codeDescription
200

OK

Code samples

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

Works with GitHub Apps

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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

Body parameters
namestringRequired

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

Can be one of: 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 response status codes

Status codeDescription
201

Created

Code samples

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

Works with 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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

HTTP response status codes

Status codeDescription
200

OK

Code samples

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

Works with GitHub Apps

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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

Body parameters
namestringRequired

Name of the runner group.

visibilitystring

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

Can be one of: selected, all, private

allows_public_repositoriesboolean

Whether the runner group can be used by public repositories.

Default: false

HTTP response status codes

Status codeDescription
200

OK

Code samples

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

Works with 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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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

Works with 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.

Parameters

Headers
acceptstring

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

Path parameters
orgstringRequired

The organization name. The name is not case sensitive.

runner_group_idintegerRequired

Unique identifier of the self-hosted runner group.

runner_idintegerRequired

Unique identifier of the self-hosted runner.

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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