REST API endpoints for self-hosted runner groups

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

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "List self-hosted runner groups for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "List self-hosted runner groups for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`
`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"

Request example

get/enterprises/{enterprise}/actions/runner-groups

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://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://HOSTNAME/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://HOSTNAME/enterprises/octo-corp/actions/runner_groups/2/organizations",
      "runners_url": "https://HOSTNAME/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://HOSTNAME/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.

OAuth app tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Create a self-hosted runner group for an enterprise"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

Parameters for "Create a self-hosted runner group for an enterprise"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Body parameters
Name, Type, Description
`name` string Required Name 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`, `all`
`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 `public` repositories. Default: `false`
`restricted_to_workflows` boolean If `true`, the runner group will be restricted to running only the workflows specified in the `selected_workflows` array. Default: `false`
`selected_workflows` array of strings List of workflows the runner group should be allowed to run. This setting will be ignored unless `restricted_to_workflows` is set to `true`.

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"

Request example

post/enterprises/{enterprise}/actions/runner-groups

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  http(s)://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://HOSTNAME/enterprises/octo-corp/actions/runner-groups/2/organizations",
  "runners_url": "https://HOSTNAME/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
}

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`runner_group_id` integer Required Unique 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`

About self-hosted runner groups in GitHub Actions

List self-hosted runner groups for an enterprise

Fine-grained access tokens for "List self-hosted runner groups for an enterprise"

Parameters for "List self-hosted runner groups for an enterprise"

HTTP response status codes for "List self-hosted runner groups for an enterprise"

Code samples for "List self-hosted runner groups for an enterprise"

Request example

Response

Create a self-hosted runner group for an enterprise

Fine-grained access tokens for "Create a self-hosted runner group for an enterprise"

Parameters for "Create a self-hosted runner group for an enterprise"

HTTP response status codes for "Create a self-hosted runner group for an enterprise"

Code samples for "Create a self-hosted runner group for an enterprise"

Request example

Response

Get a self-hosted runner group for an enterprise

Fine-grained access tokens for "Get a self-hosted runner group for an enterprise"

Parameters for "Get a self-hosted runner group for an enterprise"

HTTP response status codes for "Get a self-hosted runner group for an enterprise"