GitHub-hosted runners - GitHub Enterprise Cloud Docs

List GitHub-hosted runners for an enterprise

Lists all GitHub-hosted runners configured in 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 GitHub-hosted runners 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 GitHub-hosted runners 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`

HTTP response status codes for "List GitHub-hosted runners for an enterprise"

Status code	Description
`200`	OK

Code samples for "List GitHub-hosted runners for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners

Response

Status: 200

{
  "total_count": 2,
  "runners": [
    {
      "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"
    },
    {
      "id": 7,
      "name": "My hosted Windows runner",
      "runner_group_id": 2,
      "platform": "win-x64",
      "image": {
        "id": "windows-latest",
        "size": 256
      },
      "machine_size_details": {
        "id": "8-core",
        "cpu_cores": 8,
        "memory_gb": 32,
        "storage_gb": 300
      },
      "status": "Ready",
      "maximum_runners": 20,
      "public_ip_enabled": false,
      "public_ips": [],
      "last_active_on": "2023-04-26T15:23:37Z"
    }
  ]
}

Create a GitHub-hosted runner for an enterprise

Creates a GitHub-hosted runner for an enterprise. OAuth tokens and personal access tokens (classic) need the manage_runners:enterprise scope to use this endpoint.

Fine-grained access tokens for "Create a GitHub-hosted runner 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 GitHub-hosted runner 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.

Name, Type, Description

name string 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 '_'.

image object 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.

Properties of image

Name, Type, Description
`id` string The unique identifier of the runner image.
`source` string The source of the runner image. Can be one of: `github`, `partner`, `custom`
`version` string or null The version of the runner image to deploy. This is relevant only for runners using custom images.

size string Required

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

runner_group_id integer Required

The existing runner group to add this runner to.

maximum_runners integer

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

Default: 50

enable_static_ip boolean

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

Default: false

image_gen boolean

Whether this runner should be used to generate custom images.

Default: false

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

Status code	Description
`201`	Created

Code samples for "Create a GitHub-hosted runner for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/enterprises/{enterprise}/actions/hosted-runners

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners \
  -d '{"name":"My Hosted runner","image":{"id":"ubuntu-latest","source":"github"},"runner_group_id":1,"size":"4-core","maximum_runners":10}'

Response

Status: 201

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

List custom images for an enterprise

List custom images for an enterprise.

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

Fine-grained access tokens for "List custom images 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 custom images 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.

HTTP response status codes for "List custom images for an enterprise"

Status code	Description
`200`	OK

Code samples for "List custom images for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/custom

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom

Response

Status: 200

{
  "total_count": 2,
  "image_versions": [
    {
      "version": "1.1.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-09T23:39:01Z"
    },
    {
      "version": "1.0.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-08T20:39:01Z"
    }
  ]
}

Get an enterprise custom image definition for GitHub Actions Hosted Runners

Get an enterprise custom image definition for GitHub Actions Hosted Runners.

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

Fine-grained access tokens for "Get an enterprise custom image definition for GitHub Actions Hosted Runners"

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

Parameters for "Get an enterprise custom image definition for GitHub Actions Hosted Runners"

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.
`image_definition_id` integer Required Image definition ID of custom image

HTTP response status codes for "Get an enterprise custom image definition for GitHub Actions Hosted Runners"

Status code	Description
`200`	OK

Code samples for "Get an enterprise custom image definition for GitHub Actions Hosted Runners"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/custom/{image_definition_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID

Response

Status: 200

{
  "id": 1,
  "platform": "linux-x64",
  "name": "CustomImage",
  "source": "custom",
  "versions_count": 4,
  "total_versions_size": 200,
  "latest_version": "1.3.0",
  "state": "Ready"
}

Delete a custom image from the enterprise

Delete a custom image from the enterprise.

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

Fine-grained access tokens for "Delete a custom image from the 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 "Delete a custom image from the 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.
`image_definition_id` integer Required Image definition ID of custom image

HTTP response status codes for "Delete a custom image from the enterprise"

Status code	Description
`204`	No Content

Code samples for "Delete a custom image from the enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/actions/hosted-runners/images/custom/{image_definition_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID

Response

Status: 204

List image versions of a custom image for an enterprise

List image versions of a custom image for an enterprise.

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

Fine-grained access tokens for "List image versions of a custom image 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 image versions of a custom image for an enterprise"

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

Path parameters
Name, Type, Description
`image_definition_id` integer Required Image definition ID of custom image
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "List image versions of a custom image for an enterprise"

Status code	Description
`200`	OK

Code samples for "List image versions of a custom image for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/custom/{image_definition_id}/versions

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions

Response

Status: 200

{
  "total_count": 2,
  "image_versions": [
    {
      "version": "1.1.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-09T23:39:01Z"
    },
    {
      "version": "1.0.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-08T20:39:01Z"
    }
  ]
}

Get an image version of an enterprise custom image for GitHub Actions Hosted Runners

Get an image version of an enterprise custom image for GitHub Actions Hosted Runners.

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

Fine-grained access tokens for "Get an image version of an enterprise custom image for GitHub Actions Hosted Runners"

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

Parameters for "Get an image version of an enterprise custom image for GitHub Actions Hosted Runners"

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.
`image_definition_id` integer Required Image definition ID of custom image
`version` string Required Version of a custom image

HTTP response status codes for "Get an image version of an enterprise custom image for GitHub Actions Hosted Runners"

Status code	Description
`200`	OK

Code samples for "Get an image version of an enterprise custom image for GitHub Actions Hosted Runners"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/custom/{image_definition_id}/versions/{version}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions/VERSION

Response

Status: 200

{
  "version": "1.0.0",
  "size_gb": 75,
  "state": "Ready",
  "created_on": "2024-11-08T20:39:01Z"
}

Delete an image version of custom image from the enterprise

Delete an image version of custom image from the enterprise.

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

Fine-grained access tokens for "Delete an image version of custom image from the 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 "Delete an image version of custom image from the 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.
`image_definition_id` integer Required Image definition ID of custom image
`version` string Required Version of a custom image

HTTP response status codes for "Delete an image version of custom image from the enterprise"

Status code	Description
`204`	No Content

Code samples for "Delete an image version of custom image from the enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/actions/hosted-runners/images/custom/{image_definition_id}/versions/{version}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions/VERSION

Response

Status: 204

Get GitHub-owned images for GitHub-hosted runners in an enterprise

Get the list of GitHub-owned images available for GitHub-hosted runners for an enterprise.

Fine-grained access tokens for "Get GitHub-owned images for GitHub-hosted runners in 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 "Get GitHub-owned images for GitHub-hosted runners in 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.

HTTP response status codes for "Get GitHub-owned images for GitHub-hosted runners in an enterprise"

Status code	Description
`200`	OK

Code samples for "Get GitHub-owned images for GitHub-hosted runners in an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/github-owned

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/github-owned

Response

Status: 200

{
  "id": "ubuntu-20.04",
  "platform": "linux-x64",
  "size_gb": 86,
  "display_name": "20.04",
  "source": "github"
}

Get partner images for GitHub-hosted runners in an enterprise

Get the list of partner images available for GitHub-hosted runners for an enterprise.

Fine-grained access tokens for "Get partner images for GitHub-hosted runners in 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 "Get partner images for GitHub-hosted runners in 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.

HTTP response status codes for "Get partner images for GitHub-hosted runners in an enterprise"

Status code	Description
`200`	OK

Code samples for "Get partner images for GitHub-hosted runners in an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/images/partner

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/images/partner

Response

Status: 200

{
  "id": "ubuntu-20.04",
  "platform": "linux-x64",
  "size_gb": 86,
  "display_name": "20.04",
  "source": "github"
}

Get limits on GitHub-hosted runners for an enterprise

Get the GitHub-hosted runners limits for an enterprise.

Fine-grained access tokens for "Get limits on GitHub-hosted runners 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 "Get limits on GitHub-hosted runners 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.

HTTP response status codes for "Get limits on GitHub-hosted runners for an enterprise"

Status code	Description
`200`	OK

Code samples for "Get limits on GitHub-hosted runners for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/limits

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/limits

Response

Status: 200

{
  "public_ips": {
    "current_usage": 17,
    "maximum": 50
  }
}

Get GitHub-hosted runners machine specs for an enterprise

Get the list of machine specs available for GitHub-hosted runners for an enterprise.

Fine-grained access tokens for "Get GitHub-hosted runners machine specs 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 "Get GitHub-hosted runners machine specs 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.

HTTP response status codes for "Get GitHub-hosted runners machine specs for an enterprise"

Status code	Description
`200`	OK

Code samples for "Get GitHub-hosted runners machine specs for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/machine-sizes

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/machine-sizes

Response

Status: 200

{
  "id": "4-core",
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 150
}

Get platforms for GitHub-hosted runners in an enterprise

Get the list of platforms available for GitHub-hosted runners for an enterprise.

Fine-grained access tokens for "Get platforms for GitHub-hosted runners in 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 "Get platforms for GitHub-hosted runners in 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.

HTTP response status codes for "Get platforms for GitHub-hosted runners in an enterprise"

Status code	Description
`200`	OK

Code samples for "Get platforms for GitHub-hosted runners in an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/platforms

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/platforms

Response

Status: 200

{
  "total_count": 1,
  "platforms": [
    "linux-x64",
    "win-x64"
  ]
}

Get a GitHub-hosted runner for an enterprise

Gets a GitHub-hosted runner configured in 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 "Get a GitHub-hosted runner 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 "Get a GitHub-hosted runner 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.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

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

Status code	Description
`200`	OK

Code samples for "Get a GitHub-hosted runner for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/actions/hosted-runners/{hosted_runner_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/HOSTED_RUNNER_ID

Response

Status: 200

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

Update a GitHub-hosted runner for an enterprise

Updates a GitHub-hosted runner 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 "Update a GitHub-hosted runner 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 "Update a GitHub-hosted runner 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.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

Body parameters
Name, Type, Description
`name` string 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 '_'.
`runner_group_id` integer The existing runner group to add this runner to.
`maximum_runners` integer The maximum amount of runners to scale up to. Runners will not auto-scale above this number. Use this setting to limit your cost.
`enable_static_ip` boolean 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`
`image_version` string or null The version of the runner image to deploy. This is relevant only for runners using custom images.

HTTP response status codes for "Update a GitHub-hosted runner for an enterprise"

Status code	Description
`200`	OK

Code samples for "Update a GitHub-hosted runner for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/enterprises/{enterprise}/actions/hosted-runners/{hosted_runner_id}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/HOSTED_RUNNER_ID \
  -d '{"name":"My Hosted runner","runner_group_id":1,"maximum_runners":50,"enable_static_ip":false}'

Response

Status: 200

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

Delete a GitHub-hosted runner for an enterprise

Deletes a GitHub-hosted runner for an enterprise.

Fine-grained access tokens for "Delete a GitHub-hosted runner 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 "Delete a GitHub-hosted runner 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.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

HTTP response status codes for "Delete a GitHub-hosted runner for an enterprise"

Status code	Description
`202`	Accepted

Code samples for "Delete a GitHub-hosted runner for an enterprise"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/actions/hosted-runners/{hosted_runner_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/actions/hosted-runners/HOSTED_RUNNER_ID

Response

Status: 202

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

List GitHub-hosted runners for an organization

Lists all GitHub-hosted runners configured in an organization.

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

Fine-grained access tokens for "List GitHub-hosted runners for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "List GitHub-hosted runners for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

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`

HTTP response status codes for "List GitHub-hosted runners for an organization"

Status code	Description
`200`	OK

Code samples for "List GitHub-hosted runners for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners

Response

Status: 200

{
  "total_count": 2,
  "runners": [
    {
      "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"
    },
    {
      "id": 7,
      "name": "My hosted Windows runner",
      "runner_group_id": 2,
      "platform": "win-x64",
      "image": {
        "id": "windows-latest",
        "size": 256
      },
      "machine_size_details": {
        "id": "8-core",
        "cpu_cores": 8,
        "memory_gb": 32,
        "storage_gb": 300
      },
      "status": "Ready",
      "maximum_runners": 20,
      "public_ip_enabled": false,
      "public_ips": [],
      "last_active_on": "2023-04-26T15:23:37Z"
    }
  ]
}

Create a GitHub-hosted runner for an organization

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.

Fine-grained access tokens for "Create a GitHub-hosted runner for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (write)

Parameters for "Create a GitHub-hosted runner for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

Name, Type, Description

name string 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 '_'.

image object 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.

Properties of image

Name, Type, Description
`id` string The unique identifier of the runner image.
`source` string The source of the runner image. Can be one of: `github`, `partner`, `custom`
`version` string or null The version of the runner image to deploy. This is relevant only for runners using custom images.

size string Required

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

runner_group_id integer Required

The existing runner group to add this runner to.

maximum_runners integer

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

enable_static_ip boolean

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

image_gen boolean

Whether this runner should be used to generate custom images.

Default: false

HTTP response status codes for "Create a GitHub-hosted runner for an organization"

Status code	Description
`201`	Created

Code samples for "Create a GitHub-hosted runner for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners \
  -d '{"name":"My Hosted runner","image":{"id":"ubuntu-latest","source":"github"},"runner_group_id":1,"size":"4-core","maximum_runners":50,"enable_static_ip":false}'

Response

Status: 201

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

List custom images for an organization

List custom images for an organization.

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

Fine-grained access tokens for "List custom images for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (read)

Parameters for "List custom images for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "List custom images for an organization"

Status code	Description
`200`	OK

Code samples for "List custom images for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/custom

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom

Response

Status: 200

{
  "total_count": 2,
  "image_versions": [
    {
      "version": "1.1.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-09T23:39:01Z"
    },
    {
      "version": "1.0.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-08T20:39:01Z"
    }
  ]
}

Get a custom image definition for GitHub Actions Hosted Runners

Get a custom image definition for GitHub Actions Hosted Runners.

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

Fine-grained access tokens for "Get a custom image definition for GitHub Actions Hosted Runners"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (read)

Parameters for "Get a custom image definition for GitHub Actions Hosted Runners"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`image_definition_id` integer Required Image definition ID of custom image

HTTP response status codes for "Get a custom image definition for GitHub Actions Hosted Runners"

Status code	Description
`200`	OK

Code samples for "Get a custom image definition for GitHub Actions Hosted Runners"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/custom/{image_definition_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID

Response

Status: 200

{
  "id": 1,
  "platform": "linux-x64",
  "name": "CustomImage",
  "source": "custom",
  "versions_count": 4,
  "total_versions_size": 200,
  "latest_version": "1.3.0",
  "state": "Ready"
}

Delete a custom image from the organization

Delete a custom image from the organization.

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

Fine-grained access tokens for "Delete a custom image from the organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (write)

Parameters for "Delete a custom image from the organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`image_definition_id` integer Required Image definition ID of custom image

HTTP response status codes for "Delete a custom image from the organization"

Status code	Description
`204`	No Content

Code samples for "Delete a custom image from the organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/orgs/{org}/actions/hosted-runners/images/custom/{image_definition_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID

Response

Status: 204

List image versions of a custom image for an organization

List image versions of a custom image for an organization.

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

Fine-grained access tokens for "List image versions of a custom image for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (read)

Parameters for "List image versions of a custom image for an organization"

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

Path parameters
Name, Type, Description
`image_definition_id` integer Required Image definition ID of custom image
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "List image versions of a custom image for an organization"

Status code	Description
`200`	OK

Code samples for "List image versions of a custom image for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/custom/{image_definition_id}/versions

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions

Response

Status: 200

{
  "total_count": 2,
  "image_versions": [
    {
      "version": "1.1.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-09T23:39:01Z"
    },
    {
      "version": "1.0.0",
      "size_gb": 75,
      "state": "Ready",
      "created_on": "2024-11-08T20:39:01Z"
    }
  ]
}

Get an image version of a custom image for GitHub Actions Hosted Runners

Get an image version of a custom image for GitHub Actions Hosted Runners.

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

Fine-grained access tokens for "Get an image version of a custom image for GitHub Actions Hosted Runners"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (read)

Parameters for "Get an image version of a custom image for GitHub Actions Hosted Runners"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`image_definition_id` integer Required Image definition ID of custom image
`version` string Required Version of a custom image

HTTP response status codes for "Get an image version of a custom image for GitHub Actions Hosted Runners"

Status code	Description
`200`	OK

Code samples for "Get an image version of a custom image for GitHub Actions Hosted Runners"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/custom/{image_definition_id}/versions/{version}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions/VERSION

Response

Status: 200

{
  "version": "1.0.0",
  "size_gb": 75,
  "state": "Ready",
  "created_on": "2024-11-08T20:39:01Z"
}

Delete an image version of custom image from the organization

Delete an image version of custom image from the organization.

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

Fine-grained access tokens for "Delete an image version of custom image from the organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Hosted runner custom images" organization permissions (write)

Parameters for "Delete an image version of custom image from the organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`image_definition_id` integer Required Image definition ID of custom image
`version` string Required Version of a custom image

HTTP response status codes for "Delete an image version of custom image from the organization"

Status code	Description
`204`	No Content

Code samples for "Delete an image version of custom image from the organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/orgs/{org}/actions/hosted-runners/images/custom/{image_definition_id}/versions/{version}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/custom/IMAGE_DEFINITION_ID/versions/VERSION

Response

Status: 204

Get GitHub-owned images for GitHub-hosted runners in an organization

Get the list of GitHub-owned images available for GitHub-hosted runners for an organization.

Fine-grained access tokens for "Get GitHub-owned images for GitHub-hosted runners in an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get GitHub-owned images for GitHub-hosted runners in an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "Get GitHub-owned images for GitHub-hosted runners in an organization"

Status code	Description
`200`	OK

Code samples for "Get GitHub-owned images for GitHub-hosted runners in an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/github-owned

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/github-owned

Response

Status: 200

{
  "id": "ubuntu-20.04",
  "platform": "linux-x64",
  "size_gb": 86,
  "display_name": "20.04",
  "source": "github"
}

Get partner images for GitHub-hosted runners in an organization

Get the list of partner images available for GitHub-hosted runners for an organization.

Fine-grained access tokens for "Get partner images for GitHub-hosted runners in an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get partner images for GitHub-hosted runners in an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "Get partner images for GitHub-hosted runners in an organization"

Status code	Description
`200`	OK

Code samples for "Get partner images for GitHub-hosted runners in an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/images/partner

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/images/partner

Response

Status: 200

{
  "id": "ubuntu-20.04",
  "platform": "linux-x64",
  "size_gb": 86,
  "display_name": "20.04",
  "source": "github"
}

Get limits on GitHub-hosted runners for an organization

Get the GitHub-hosted runners limits for an organization.

Fine-grained access tokens for "Get limits on GitHub-hosted runners for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get limits on GitHub-hosted runners for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "Get limits on GitHub-hosted runners for an organization"

Status code	Description
`200`	OK

Code samples for "Get limits on GitHub-hosted runners for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/limits

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/limits

Response

Status: 200

{
  "public_ips": {
    "current_usage": 17,
    "maximum": 50
  }
}

Get GitHub-hosted runners machine specs for an organization

Get the list of machine specs available for GitHub-hosted runners for an organization.

Fine-grained access tokens for "Get GitHub-hosted runners machine specs for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get GitHub-hosted runners machine specs for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "Get GitHub-hosted runners machine specs for an organization"

Status code	Description
`200`	OK

Code samples for "Get GitHub-hosted runners machine specs for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/machine-sizes

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/machine-sizes

Response

Status: 200

{
  "id": "4-core",
  "cpu_cores": 4,
  "memory_gb": 16,
  "storage_gb": 150
}

Get platforms for GitHub-hosted runners in an organization

Get the list of platforms available for GitHub-hosted runners for an organization.

Fine-grained access tokens for "Get platforms for GitHub-hosted runners in an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get platforms for GitHub-hosted runners in an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.

HTTP response status codes for "Get platforms for GitHub-hosted runners in an organization"

Status code	Description
`200`	OK

Code samples for "Get platforms for GitHub-hosted runners in an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/orgs/{org}/actions/hosted-runners/platforms

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/platforms

Response

Status: 200

{
  "total_count": 1,
  "platforms": [
    "linux-x64",
    "win-x64"
  ]
}

Get a GitHub-hosted runner for an organization

Gets a GitHub-hosted runner configured in an organization.

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

Fine-grained access tokens for "Get a GitHub-hosted runner for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (read)

Parameters for "Get a GitHub-hosted runner for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

HTTP response status codes for "Get a GitHub-hosted runner for an organization"

Status code	Description
`200`	OK

Code samples for "Get a GitHub-hosted runner for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/HOSTED_RUNNER_ID

Response

Status: 200

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

Update a GitHub-hosted runner for an organization

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.

Fine-grained access tokens for "Update a GitHub-hosted runner for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (write)

Parameters for "Update a GitHub-hosted runner for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

Body parameters
Name, Type, Description
`name` string 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 '_'.
`runner_group_id` integer The existing runner group to add this runner to.
`maximum_runners` integer The maximum amount of runners to scale up to. Runners will not auto-scale above this number. Use this setting to limit your cost.
`enable_static_ip` boolean 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`
`image_version` string or null The version of the runner image to deploy. This is relevant only for runners using custom images.

HTTP response status codes for "Update a GitHub-hosted runner for an organization"

Status code	Description
`200`	OK

Code samples for "Update a GitHub-hosted runner for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/HOSTED_RUNNER_ID \
  -d '{"name":"My larger runner","runner_group_id":1,"maximum_runners":50,"enable_static_ip":false}'

Response

Status: 200

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

Delete a GitHub-hosted runner for an organization

Deletes a GitHub-hosted runner for an organization.

Fine-grained access tokens for "Delete a GitHub-hosted runner for an organization"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Administration" organization permissions (write)

Parameters for "Delete a GitHub-hosted runner for an organization"

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

Path parameters
Name, Type, Description
`org` string Required The organization name. The name is not case sensitive.
`hosted_runner_id` integer Required Unique identifier of the GitHub-hosted runner.

HTTP response status codes for "Delete a GitHub-hosted runner for an organization"

Status code	Description
`202`	Accepted

Code samples for "Delete a GitHub-hosted runner for an organization"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/orgs/ORG/actions/hosted-runners/HOSTED_RUNNER_ID

Response

Status: 202

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