Skip to content
forgit api docs

Update a GitHub-hosted runner for an organization

PATCH
/orgs/{org}/actions/hosted-runners/{hosted_runner_id}

Updates a GitHub-hosted runner for an organization. OAuth app 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.

hosted_runner_id
required
integer

Unique identifier of the GitHub-hosted runner.

Request Body required

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

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
runner_group_id

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 updated with a static public IP. Note limit on account. To list limits on account, use GET actions/hosted-runners/limits

boolean
size

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

string
image_source

The source type of the runner image to use. Must match the source of the image specified by image_id. Can be one of github, partner, or custom.

string
Allowed values: github partner custom
image_id

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

string
image_version

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

string
nullable
image_gen

Whether to enable image generation for this runner pool. When enabled, the runner pool is used to build and publish custom runner images.

boolean
Examples
Example default 
{
  "name": "My larger runner",
  "runner_group_id": 1,
  "maximum_runners": 50,
  "enable_static_ip": false
}

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

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"
}