Skip to main content
Die REST-API verfügt jetzt über eine Versionskontrolle. Weitere Informationen findest du unter Informationen zur API-Versionsverwaltung.

GitHub-hosted runners

Use the REST API to interact with GitHub-hosted runners in GitHub Actions.

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.

Differenzierte Zugriffstoken für "List GitHub-hosted runners for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „List GitHub-hosted runners for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

Abfrageparameter
Name, type, BESCHREIBUNG
per_page integer

The number of results per page (max 100). For more information, see "Using pagination in the REST API."

Standard: 30

page integer

The page number of the results to fetch. For more information, see "Using pagination in the REST API."

Standard: 1

HTTP-Antwortstatuscodes für „List GitHub-hosted runners for an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „List GitHub-hosted runners for an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Create a GitHub-hosted runner for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (write)

Parameter für „Create a GitHub-hosted runner for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

Textparameter
Name, type, BESCHREIBUNG
name string Erforderlich

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 Erforderlich

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

Name, type, BESCHREIBUNG
id string

The unique identifier of the runner image.

source string

The source of the runner image.

Kann eine der Folgenden sein: 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 Erforderlich

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

runner_group_id integer Erforderlich

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

HTTP-Antwortstatuscodes für „Create a GitHub-hosted runner for an organization“

StatuscodeBESCHREIBUNG
201

Created

Codebeispiele für „Create a GitHub-hosted runner for an organization“

Anforderungsbeispiel

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","version":"latest"},"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" }

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.

Differenzierte Zugriffstoken für "Get GitHub-owned images for GitHub-hosted runners in an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get GitHub-owned images for GitHub-hosted runners in an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

HTTP-Antwortstatuscodes für „Get GitHub-owned images for GitHub-hosted runners in an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get GitHub-owned images for GitHub-hosted runners in an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Get partner images for GitHub-hosted runners in an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get partner images for GitHub-hosted runners in an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

HTTP-Antwortstatuscodes für „Get partner images for GitHub-hosted runners in an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get partner images for GitHub-hosted runners in an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Get limits on GitHub-hosted runners for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get limits on GitHub-hosted runners for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

HTTP-Antwortstatuscodes für „Get limits on GitHub-hosted runners for an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get limits on GitHub-hosted runners for an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Get GitHub-hosted runners machine specs for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get GitHub-hosted runners machine specs for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

HTTP-Antwortstatuscodes für „Get GitHub-hosted runners machine specs for an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get GitHub-hosted runners machine specs for an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Get platforms for GitHub-hosted runners in an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get platforms for GitHub-hosted runners in an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

HTTP-Antwortstatuscodes für „Get platforms for GitHub-hosted runners in an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get platforms for GitHub-hosted runners in an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Get a GitHub-hosted runner for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (read)

Parameter für „Get a GitHub-hosted runner for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

hosted_runner_id integer Erforderlich

Unique identifier of the GitHub-hosted runner.

HTTP-Antwortstatuscodes für „Get a GitHub-hosted runner for an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Get a GitHub-hosted runner for an organization“

Anforderungsbeispiel

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.

Differenzierte Zugriffstoken für "Update a GitHub-hosted runner for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (write)

Parameter für „Update a GitHub-hosted runner for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

hosted_runner_id integer Erforderlich

Unique identifier of the GitHub-hosted runner.

Textparameter
Name, type, BESCHREIBUNG
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-Antwortstatuscodes für „Update a GitHub-hosted runner for an organization“

StatuscodeBESCHREIBUNG
200

OK

Codebeispiele für „Update a GitHub-hosted runner for an organization“

Anforderungsbeispiel

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,"image_version":"1.0.0"}'

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.

Differenzierte Zugriffstoken für "Delete a GitHub-hosted runner for an organization"

Dieser Endpunkt funktioniert mit den folgenden differenzierten Tokentypen.:

Das differenzierte Token muss einen der folgenden Berechtigungssätze aufweisen.:

  • "Administration" organization permissions (write)

Parameter für „Delete a GitHub-hosted runner for an organization“

Header
Name, type, BESCHREIBUNG
accept string

Setting to application/vnd.github+json is recommended.

Pfadparameter
Name, type, BESCHREIBUNG
org string Erforderlich

The organization name. The name is not case sensitive.

hosted_runner_id integer Erforderlich

Unique identifier of the GitHub-hosted runner.

HTTP-Antwortstatuscodes für „Delete a GitHub-hosted runner for an organization“

StatuscodeBESCHREIBUNG
202

Accepted

Codebeispiele für „Delete a GitHub-hosted runner for an organization“

Anforderungsbeispiel

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