Skip to content
forgit api docs

Create a self-hosted runner group for an organization

POST
/orgs/{org}/actions/runner-groups

Creates a new self-hosted runner group for an organization.

OAuth tokens and personal access tokens (classic) need the admin:org scope to use this endpoint.

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
name
required

Name of the runner group.

string
visibility

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

string
default: all
Allowed values: selected all private
selected_repository_ids

List of repository IDs that can access the runner group.

Array<integer>
runners

List of runner IDs to add to the runner group.

Array<integer>
allows_public_repositories

Whether the runner group can be used by public repositories.

boolean
restricted_to_workflows

If true, the runner group will be restricted to running only the workflows specified in the selected_workflows array.

boolean
selected_workflows

List of workflows the runner group should be allowed to run. This setting will be ignored unless restricted_to_workflows is set to true.

Array<string>
network_configuration_id

The identifier of a hosted compute network configuration.

string
Examples
Example default 
{
  "name": "Expensive hardware runners",
  "visibility": "selected",
  "selected_repository_ids": [
    32,
    91
  ],
  "runners": [
    9,
    2
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
object
id
required
number
name
required
string
visibility
required
string
default
required
boolean
selected_repositories_url

Link to the selected repositories resource for this runner group. Not present unless visibility was set to selected

string
runners_url
required
string
hosted_runners_url
string
network_configuration_id

The identifier of a hosted compute network configuration.

string
inherited
required
boolean
inherited_allows_public_repositories
boolean
allows_public_repositories
required
boolean
workflow_restrictions_read_only

If true, the restricted_to_workflows and selected_workflows fields cannot be modified.

boolean
restricted_to_workflows

If true, the runner group will be restricted to running only the workflows specified in the selected_workflows array.

boolean
selected_workflows

List of workflows the runner group should be allowed to run. This setting will be ignored unless restricted_to_workflows is set to true.

Array<string>
Examples
Example default 
{
  "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",
  "hosted_runners_url": "https://api.github.com/orgs/octo-org/actions/runner_groups/2/hosted-runners",
  "network_configuration_id": "EC486D5D793175D7E3B29C27318D5C1AAE49A7833FC85F2E82C3D2C54AC7D3BA",
  "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
}