org_hosted_runners

Creates, updates, deletes, gets or lists an org_hosted_runners resource.

Overview

Name	org_hosted_runners
Type	Resource
Id	github.actions.org_hosted_runners

Fields

The following fields are returned by SELECT queries:

get_hosted_runner_for_org

Response

Name	Datatype	Description
id	integer	The unique identifier of the hosted runner.
name	string	The name of the hosted runner. (example: my-github-hosted-runner)
runner_group_id	integer	The unique identifier of the group that the hosted runner belongs to.
image_details	object	Provides details of a hosted runner image (title: GitHub-hosted runner image details.)
image_gen	boolean	Whether custom image generation is enabled for the hosted runners.
last_active_on	string (date-time)	The time at which the runner was last used, in ISO 8601 format. (example: 2022-10-09T23:39:01Z)
machine_size_details	object	Provides details of a particular machine spec. (title: Github-owned VM details.)
maximum_runners	integer	The maximum amount of hosted runners. Runners will not scale automatically above this number. Use this setting to limit your cost.
platform	string	The operating system of the image. (example: linux-x64)
public_ip_enabled	boolean	Whether public IP is enabled for the hosted runners.
public_ips	array	The public IP ranges when public IP is enabled for the hosted runners.
status	string	The status of the runner. (Ready, Provisioning, Shutdown, Deleting, Stuck) (example: Ready)

list_hosted_runners_for_org

Response

Name	Datatype	Description
runners	array
total_count	integer

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_hosted_runner_for_org	select	org, hosted_runner_id		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.
list_hosted_runners_for_org	select	org	per_page, page	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.
create_hosted_runner_for_org	insert	org, name, image, size, runner_group_id		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.
update_hosted_runner_for_org	update	org, hosted_runner_id		Updates a GitHub-hosted runner for an organization. OAuth app tokens and personal access tokens (classic) need the manage_runners:org scope to use this endpoint.
delete_hosted_runner_for_org	delete	org, hosted_runner_id		Deletes a GitHub-hosted runner for an organization.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
hosted_runner_id	integer	Unique identifier of the GitHub-hosted runner.
org	string	The organization name. The name is not case sensitive.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."

SELECT examples

get_hosted_runner_for_org

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.

SELECT
id,
name,
runner_group_id,
image_details,
image_gen,
last_active_on,
machine_size_details,
maximum_runners,
platform,
public_ip_enabled,
public_ips,
status
FROM github.actions.org_hosted_runners
WHERE org = '{{ org }}' -- required
AND hosted_runner_id = '{{ hosted_runner_id }}' -- required
;

list_hosted_runners_for_org

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.

SELECT
runners,
total_count
FROM github.actions.org_hosted_runners
WHERE org = '{{ org }}' -- required
AND per_page = '{{ per_page }}'
AND page = '{{ page }}'
;

INSERT examples

create_hosted_runner_for_org

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.

INSERT INTO github.actions.org_hosted_runners (
name,
image,
size,
runner_group_id,
maximum_runners,
enable_static_ip,
image_gen,
org
)
SELECT 
'{{ name }}' /* required */,
'{{ image }}' /* required */,
'{{ size }}' /* required */,
{{ runner_group_id }} /* required */,
{{ maximum_runners }},
{{ enable_static_ip }},
{{ image_gen }},
'{{ org }}'
RETURNING
id,
name,
runner_group_id,
image_details,
image_gen,
last_active_on,
machine_size_details,
maximum_runners,
platform,
public_ip_enabled,
public_ips,
status
;

Manifest

# Description fields are for documentation purposes
- name: org_hosted_runners
props:
  - name: org
    value: "{{ org }}"
    description: Required parameter for the org_hosted_runners resource.
  - name: name
    value: "{{ name }}"
    description: |
      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 '_'.
  - name: image
    description: |
      The image of runner. To list all available images, use `GET /actions/hosted-runners/images/github-owned` or `GET /actions/hosted-runners/images/partner`.
    value:
      id: "{{ id }}"
      source: "{{ source }}"
      version: "{{ version }}"
  - name: size
    value: "{{ size }}"
    description: |
      The machine size of the runner. To list available sizes, use `GET actions/hosted-runners/machine-sizes`
  - name: runner_group_id
    value: {{ runner_group_id }}
    description: |
      The existing runner group to add this runner to.
  - name: maximum_runners
    value: {{ maximum_runners }}
    description: |
      The maximum amount of runners to scale up to. Runners will not auto-scale above this number. Use this setting to limit your cost.
  - name: enable_static_ip
    value: {{ enable_static_ip }}
    description: |
      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`
  - name: image_gen
    value: {{ image_gen }}
    description: |
      Whether this runner should be used to generate custom images.
    default: false

UPDATE examples

update_hosted_runner_for_org

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.

UPDATE github.actions.org_hosted_runners
SET 
name = '{{ name }}',
runner_group_id = {{ runner_group_id }},
maximum_runners = {{ maximum_runners }},
enable_static_ip = {{ enable_static_ip }},
size = '{{ size }}',
image_id = '{{ image_id }}',
image_version = '{{ image_version }}'
WHERE 
org = '{{ org }}' --required
AND hosted_runner_id = '{{ hosted_runner_id }}' --required
RETURNING
id,
name,
runner_group_id,
image_details,
image_gen,
last_active_on,
machine_size_details,
maximum_runners,
platform,
public_ip_enabled,
public_ips,
status;

DELETE examples

delete_hosted_runner_for_org

Deletes a GitHub-hosted runner for an organization.

DELETE FROM github.actions.org_hosted_runners
WHERE org = '{{ org }}' --required
AND hosted_runner_id = '{{ hosted_runner_id }}' --required
;