ci.runner-pools.create

Create a runner pool

POST /ci/api/runner-poolsIAM ci:CreateRunnerPoolChanges state

Creates a launch template and an auto scaling group named runner-pool-<name> in your organization (also needs autoscaling:CreateLaunchTemplate, autoscaling:CreateAutoScalingGroup and ec2:RunInstances). A job whose runs-on labels are all among the pool’s goes to it, with or without self-hosted in the file: give a pool ubuntu-latest and ubuntu-24.04 to move hosted jobs onto per-job machines. Idle machines stay until shortly before their paid hour ends.

Request syntax

POST /ci/api/runner-pools
{
  "name": "string",
  "labels": "array of string",
  "size": "enum",
  "minSize": "number",
  "maxSize": "number",
  "spare": "number",
  "cleanMachinePerJob": "boolean",
  "shareTrustedMachines": "boolean",
  "prebuiltImage": "boolean",
  "placement": "enum",
  "runnerGroupId": "string"
}

Request body

  • nameRequired

    string

    Name of the pool, lower-case letters, digits and -, up to 40, unique in the organization (409); its group and template are named runner-pool-<name>

    Constraints: /^[a-z0-9][a-z0-9-]{0,39}$/

  • labelsRequired

    array of string

    Jobs whose runs-on labels are all among these go here, e.g. ubuntu-latest, ubuntu-24.04 (hosted jobs) or hetzner-16; 1 to 20, each up to 50 characters; a macOS label is refused (400)

    Constraints: /^[a-z0-9][a-z0-9._-]{0,49}$/

  • sizeRequired

    enum

    Machine size: s-2 (2 vCPU / 4 GiB), s-4 (4 / 8), s-8 (8 / 16), s-16 (16 / 32), d-2, d-8 (dedicated), a-2, a-4, a-8, a-16 (ARM, for ubuntu-24.04-arm jobs); the smallest machine of your provider that fits

    One of: s-2, s-4, s-8, s-16, m-4, d-2, d-8, a-2, a-4, a-8, a-16

  • minSizeOptional

    number

    Machines always on (the base), 0 to 200, not above maxSize (400); 0 when omitted

    Constraints: integer, 0-200

  • maxSizeRequired

    number

    Most machines at once, 1 to 200

    Constraints: integer, 1-200

  • spareOptional

    number

    Idle machines kept above demand, 0 to 50; 0 when omitted

    Constraints: integer, 0-50

  • cleanMachinePerJobOptional

    boolean

    Destroy every machine after its job instead of reusing it within its paid hour; off when omitted

  • shareTrustedMachinesOptional

    boolean

    Let trusted jobs (default branch, tags, dispatch, schedules) of every repository share machines; pull request jobs never do; off when omitted

  • prebuiltImageOptional

    boolean

    Start machines from the organization's pre-built runner image once it is built (first job about a minute sooner); default true; false: stock Ubuntu, installed at every boot

  • placementOptional

    enum

    own-hosts-first (default): each machine runs on the platform's own CI hosts when one has room, in the cloud otherwise, and each job says where and why; cloud-only: always at your organization's provider

    One of: own-hosts-first, cloud-only

  • runnerGroupIdOptional

    string

    A runner group whose repository and ref rules decide which runs reach the pool

    Constraints: uuid

Response

201 with the new pool as the list shows it, in the caller's region. 400 when minSize is above maxSize, a label is a macOS label, the region has no zone, or the size cannot be launched; 404 when runnerGroupId is not a group of this organization; 409 when the name is taken; 403 without the three actions named below as well.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow ci:CreateRunnerPool on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud ci runner-pools create --name example --labels '["example"]' --size s-2 --max-size 1

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_ci_runner-pools_create.