Sample - GitHub REST API
POST/orgs/{org}/actions/hosted-runners

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.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

1 parameter · 7 body fields
orgstringrequired
The organization name. The name is not case sensitive.
namestringrequired
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 '_'.
imageobjectrequired
The image of runner. To list all available images, use `GET /actions/hosted-runners/images/github-owned` or `GET /actions/hosted-runners/images/partner`.
sizestringrequired
The machine size of the runner. To list available sizes, use `GET actions/hosted-runners/machine-sizes`
runner_group_idintegerrequired
The existing runner group to add this runner to.
maximum_runnersintegeroptional
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_ipbooleanoptional
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_genbooleanoptional
Whether this runner should be used to generate custom images.
Default:false

1 status code
201Response
idintegerrequired
The unique identifier of the hosted runner.
namestringrequired
The name of the hosted runner.
runner_group_idintegeroptional
The unique identifier of the group that the hosted runner belongs to.
image_detailsobjectrequired
Provides details of a hosted runner image
machine_size_detailsobjectrequired
Provides details of a particular machine spec.
statusstringrequired
The status of the runner.
Allowed:ReadyProvisioningShutdownDeletingStuck
platformstringrequired
The operating system of the image.
maximum_runnersintegeroptional
The maximum amount of hosted runners. Runners will not scale automatically above this number. Use this setting to limit your cost.
Default:10
public_ip_enabledbooleanrequired
Whether public IP is enabled for the hosted runners.
public_ipsarray<PublicIPForAGitHubHostedLargerRunners>optional
The public IP ranges when public IP is enabled for the hosted runners.
last_active_onstringoptional
The time at which the runner was last used, in ISO 8601 format.
image_genbooleanoptional
Whether custom image generation is enabled for the hosted runners.