Skip to content
forgit api docs

Create a GitHub-hosted runner for an organization

POST
/orgs/{org}/actions/hosted-runners

Creates a GitHub-hosted runner for an organization. OAuth tokens and personal access tokens (classic) need the manage_runners: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. Must be between 1 and 64 characters and may only contain upper and lowercase letters a-z, numbers 0-9, ‘.’, ‘-’, and ‘_’.

string
image
required

The image of runner. To list all available images, use GET /actions/hosted-runners/images/github-owned or GET /actions/hosted-runners/images/partner.

object
id

The unique identifier of the runner image.

string
source

The source of the runner image.

string
Allowed values: github partner custom
version

The version of the runner image to deploy. This is relevant only for runners using custom images.

string
nullable
size
required

The machine size of the runner. To list available sizes, use GET actions/hosted-runners/machine-sizes

string
runner_group_id
required

The existing runner group to add this runner to.

integer
maximum_runners

The maximum amount of runners to scale up to. Runners will not auto-scale above this number. Use this setting to limit your cost.

integer
enable_static_ip

Whether this runner should be created with a static public IP. Note limit on account. To list limits on account, use GET actions/hosted-runners/limits

boolean
image_gen

Whether this runner should be used to generate custom images.

boolean
Examples
Example default 
{
  "name": "My Hosted runner",
  "image": {
    "id": "ubuntu-latest",
    "source": "github"
  },
  "runner_group_id": 1,
  "size": "4-core",
  "maximum_runners": 50,
  "enable_static_ip": false
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Response

Media type application/json
GitHub-hosted hosted runner

A Github-hosted hosted runner.

object
id
required

The unique identifier of the hosted runner.

integer
name
required

The name of the hosted runner.

string
runner_group_id

The unique identifier of the group that the hosted runner belongs to.

integer
image_details
required
GitHub-hosted runner image details.

Provides details of a hosted runner image

object
id
required

The ID of the image. Use this ID for the image parameter when creating a new larger runner.

string
size_gb
required

Image size in GB.

integer
display_name
required

Display name for this image.

string
source
required

The image provider.

string
Allowed values: github partner custom
version

The image version of the hosted runner pool.

string
machine_size_details
required
Github-owned VM details.

Provides details of a particular machine spec.

object
id
required

The ID used for the size parameter when creating a new runner.

string
cpu_cores
required

The number of cores.

integer
memory_gb
required

The available RAM for the machine spec.

integer
storage_gb
required

The available SSD storage for the machine spec.

integer
status
required

The status of the runner.

string
Allowed values: Ready Provisioning Shutdown Deleting Stuck
platform
required

The operating system of the image.

string
maximum_runners

The maximum amount of hosted runners. Runners will not scale automatically above this number. Use this setting to limit your cost.

integer
default: 10
public_ip_enabled
required

Whether public IP is enabled for the hosted runners.

boolean
public_ips

The public IP ranges when public IP is enabled for the hosted runners.

Array<object>
Public IP for a GitHub-hosted larger runners.

Provides details of Public IP for a GitHub-hosted larger runners

object
enabled

Whether public IP is enabled.

boolean
prefix

The prefix for the public IP.

string
length

The length of the IP prefix.

integer
last_active_on

The time at which the runner was last used, in ISO 8601 format.

string format: date-time
nullable
image_gen

Whether custom image generation is enabled for the hosted runners.

boolean
Examples
Example default 
{
  "id": 5,
  "name": "My hosted ubuntu runner",
  "runner_group_id": 2,
  "platform": "linux-x64",
  "image": {
    "id": "ubuntu-20.04",
    "size": 86
  },
  "machine_size_details": {
    "id": "4-core",
    "cpu_cores": 4,
    "memory_gb": 16,
    "storage_gb": 150
  },
  "status": "Ready",
  "maximum_runners": 10,
  "public_ip_enabled": true,
  "public_ips": [
    {
      "enabled": true,
      "prefix": "20.80.208.150",
      "length": 31
    }
  ],
  "last_active_on": "2022-10-09T23:39:01Z"
}