Self-hosted runner groups
Use the REST API to interact with self-hosted runner groups for GitHub Actions.
About self-hosted runner groups in GitHub Actions
You can use the REST API to manage groups of self-hosted runners in GitHub Actions. For more information, see "Managing access to self-hosted runners using groups."
These endpoints are available for authenticated users, OAuth Apps, and GitHub Apps. Access tokens require repo
scope for private repositories and public_repo
scope for internal repositories. GitHub Apps must have the administration
permission for repositories or the organization_self_hosted_runners
permission for organizations. Authenticated users must have admin access to repositories or organizations, or the manage_runners:enterprise
scope for enterprises to use these endpoints.
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 for "List self-hosted runner groups for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
Query parameters |
Name, Type, Description |
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
visible_to_organization string Only return runner groups that are allowed to be used by this organization. |
HTTP response status codes for "List self-hosted runner groups for an enterprise"
Status code | Description |
---|---|
200 | OK |
Code samples for "List self-hosted runner groups for an enterprise"
curl -L \
-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,
"restricted_to_workflows": false,
"selected_workflows": [],
"workflow_restrictions_read_only": 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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
},
{
"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,
"restricted_to_workflows": false,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
]
}
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 for "Create a self-hosted runner group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
Body parameters |
Name, Type, Description |
name string RequiredName of the runner group. |
visibility string Visibility of a runner group. You can select all organizations or select individual organization. Can be one of: |
selected_organization_ids array of integers List of organization IDs that can access the runner group. |
runners array of integers List of runner IDs to add to the runner group. |
allows_public_repositories boolean Whether the runner group can be used by Default: |
HTTP response status codes for "Create a self-hosted runner group for an enterprise"
Status code | Description |
---|---|
201 | Created |
Code samples for "Create a self-hosted runner group for an enterprise"
curl -L \
-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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": 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 for "Get a self-hosted runner group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
HTTP response status codes for "Get a self-hosted runner group for an enterprise"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a self-hosted runner group for an enterprise"
curl -L \
-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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": 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 for "Update a self-hosted runner group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
Body parameters |
Name, Type, Description |
name string Name of the runner group. |
visibility string Visibility of a runner group. You can select all organizations or select individual organizations. Default: Can be one of: |
allows_public_repositories boolean Whether the runner group can be used by Default: |
HTTP response status codes for "Update a self-hosted runner group for an enterprise"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a self-hosted runner group for an enterprise"
curl -L \
-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,
"restricted_to_workflows": false,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
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 for "Delete a self-hosted runner group from an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
HTTP response status codes for "Delete a self-hosted runner group from an enterprise"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Delete a self-hosted runner group from an enterprise"
curl -L \
-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 for "List self-hosted runners in a group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
Query parameters |
Name, Type, Description |
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
HTTP response status codes for "List self-hosted runners in a group for an enterprise"
Status code | Description |
---|---|
200 | OK |
Code samples for "List self-hosted runners in a group for an enterprise"
curl -L \
-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 for "Set self-hosted runners in a group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
Body parameters |
Name, Type, Description |
runners array of integers RequiredList of runner IDs to add to the runner group. |
HTTP response status codes for "Set self-hosted runners in a group for an enterprise"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Set self-hosted runners in a group for an enterprise"
curl -L \
-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 for "Add a self-hosted runner to a group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
runner_id integer RequiredUnique identifier of the self-hosted runner. |
HTTP response status codes for "Add a self-hosted runner to a group for an enterprise"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Add a self-hosted runner to a group for an enterprise"
curl -L \
-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 for "Remove a self-hosted runner from a group for an enterprise"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
enterprise string RequiredThe slug version of the enterprise name. You can also substitute this value with the enterprise id. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
runner_id integer RequiredUnique identifier of the self-hosted runner. |
HTTP response status codes for "Remove a self-hosted runner from a group for an enterprise"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Remove a self-hosted runner from a group for an enterprise"
curl -L \
-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
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 for "List self-hosted runner groups for an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
Query parameters |
Name, Type, Description |
per_page integer The number of results per page (max 100). Default: |
page integer Page number of the results to fetch. Default: |
HTTP response status codes for "List self-hosted runner groups for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "List self-hosted runner groups for an organization"
curl -L \
-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,
"restricted_to_workflows": false,
"selected_workflows": [],
"workflow_restrictions_read_only": false
},
{
"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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": 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,
"restricted_to_workflows": false,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
]
}
Create a self-hosted runner group for an organization
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 for "Create a self-hosted runner group for an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
Body parameters |
Name, Type, Description |
name string RequiredName of the runner group. |
visibility string Visibility of a runner group. You can select all repositories, select individual repositories, or limit access to private repositories. Default: Can be one of: |
selected_repository_ids array of integers List of repository IDs that can access the runner group. |
runners array of integers List of runner IDs to add to the runner group. |
allows_public_repositories boolean Whether the runner group can be used by Default: |
restricted_to_workflows boolean If Default: |
selected_workflows array of strings List of workflows the runner group should be allowed to run. This setting will be ignored unless |
HTTP response status codes for "Create a self-hosted runner group for an organization"
Status code | Description |
---|---|
201 | Created |
Code samples for "Create a self-hosted runner group for an organization"
curl -L \
-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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
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.
Parameters for "Get a self-hosted runner group for an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
HTTP response status codes for "Get a self-hosted runner group for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Get a self-hosted runner group for an organization"
curl -L \
-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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
Update a self-hosted runner group for an organization
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 for "Update a self-hosted runner group for an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
Body parameters |
Name, Type, Description |
name string RequiredName of the runner group. |
visibility string Visibility of a runner group. You can select all repositories, select individual repositories, or all private repositories. Can be one of: |
allows_public_repositories boolean Whether the runner group can be used by Default: |
restricted_to_workflows boolean If Default: |
selected_workflows array of strings List of workflows the runner group should be allowed to run. This setting will be ignored unless |
HTTP response status codes for "Update a self-hosted runner group for an organization"
Status code | Description |
---|---|
200 | OK |
Code samples for "Update a self-hosted runner group for an organization"
curl -L \
-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,
"restricted_to_workflows": true,
"selected_workflows": [
"octo-org/octo-repo/.github/workflows/deploy.yaml@refs/heads/main"
],
"workflow_restrictions_read_only": false
}
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.
Parameters for "Delete a self-hosted runner group from an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
HTTP response status codes for "Delete a self-hosted runner group from an organization"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Delete a self-hosted runner group from an organization"
curl -L \
-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
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 for "Add a self-hosted runner to a group for an organization"
Headers |
---|
Name, Type, Description |
accept string Setting to |
Path parameters |
Name, Type, Description |
org string RequiredThe organization name. The name is not case sensitive. |
runner_group_id integer RequiredUnique identifier of the self-hosted runner group. |
runner_id integer RequiredUnique identifier of the self-hosted runner. |
HTTP response status codes for "Add a self-hosted runner to a group for an organization"
Status code | Description |
---|---|
204 | No Content |
Code samples for "Add a self-hosted runner to a group for an organization"
curl -L \
-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