Executores hospedados no GitHub - Documentos do GitHub

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.

Tokens de acesso granulares para "List GitHub-hosted runners for an organization"

Este endpoint funciona com os seguintes tipos de token granulares:

O token refinado deve ter os seguintes conjuntos de permissões:

"Administration" organization permissions (read)

Parâmetros para "List GitHub-hosted runners for an organization"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`org` string Obrigatório The organization name. The name is not case sensitive.

Parâmetros de consulta
Nome, Tipo, Descrição
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Padrão: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Padrão: `1`

Códigos de status de resposta HTTP para "List GitHub-hosted runners for an organization"

Código de status	Descrição
`200`	OK

Exemplos de código para "List GitHub-hosted runners for an organization"

Exemplo de solicitação

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

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  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.

Tokens de acesso granulares para "Create a GitHub-hosted runner for an organization"

Este endpoint funciona com os seguintes tipos de token granulares:

O token refinado deve ter os seguintes conjuntos de permissões:

"Administration" organization permissions (write)

Parâmetros para "Create a GitHub-hosted runner for an organization"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`org` string Obrigatório The organization name. The name is not case sensitive.

Nome, Tipo, Descrição

name string Obrigatório

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 Obrigatório

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

Nome, Tipo, Descrição
`id` string The unique identifier of the runner image.
`source` string The source of the runner image. Pode ser um dos: `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 Obrigatório

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

runner_group_id integer Obrigatório

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.

Padrão: false

Códigos de status de resposta HTTP para "Create a GitHub-hosted runner for an organization"

Código de status	Descrição
`201`	Created

Exemplos de código para "Create a GitHub-hosted runner for an organization"

Exemplo de solicitação

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: 2026-03-10" \
  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.

Tokens de acesso granulares para "List custom images for an organization"

Este endpoint funciona com os seguintes tipos de token granulares:

O token refinado deve ter os seguintes conjuntos de permissões:

"Hosted runner custom images" organization permissions (read)

Parâmetros para "List custom images for an organization"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`org` string Obrigatório The organization name. The name is not case sensitive.

Códigos de status de resposta HTTP para "List custom images for an organization"

Código de status	Descrição
`200`	OK

Exemplos de código para "List custom images for an organization"

Exemplo de solicitação

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: 2026-03-10" \
  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.

Tokens de acesso granulares para "Get a custom image definition for GitHub Actions Hosted Runners"

Este endpoint funciona com os seguintes tipos de token granulares:

O token refinado deve ter os seguintes conjuntos de permissões:

"Hosted runner custom images" organization permissions (read)

Parâmetros para "Get a custom image definition for GitHub Actions Hosted Runners"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`org` string Obrigatório The organization name. The name is not case sensitive.
`image_definition_id` integer Obrigatório Image definition ID of custom image

Códigos de status de resposta HTTP para "Get a custom image definition for GitHub Actions Hosted Runners"

Código de status	Descrição
`200`	OK

Exemplos de código para "Get a custom image definition for GitHub Actions Hosted Runners"

Exemplo de solicitação

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: 2026-03-10" \
  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.

Tokens de acesso granulares para "Delete a custom image from the organization"

Este endpoint funciona com os seguintes tipos de token granulares:

O token refinado deve ter os seguintes conjuntos de permissões:

"Hosted runner custom images" organization permissions (write)

Parâmetros para "Delete a custom image from the organization"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`org` string Obrigatório The organization name. The name is not case sensitive.
`image_definition_id` integer Obrigatório Image definition ID of custom image

Códigos de status de resposta HTTP para "Delete a custom image from the organization"

Código de status	Descrição
`204`	No Content

Exemplos de código para "Delete a custom image from the organization"

Exemplo de solicitação

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: 2026-03-10" \
  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.

Tokens de acesso granulares para "List image versions of a custom image for an organization"

Este endpoint funciona com os seguintes tipos de token granulares:

tokens de acesso do usuário do aplicativo GitHub