ci.runner-pools.update

Change a pool’s labels, sizes, spare machines or machine reuse

PATCH /ci/api/runner-pools/{id}IAM ci:UpdateRunnerPoolChanges state

Request syntax

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

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • labelsOptional

    array of string

    Replaces the labels: 1 to 20, each letters, digits, . _ -, up to 50, lower-cased; no macOS label (400); omitted: unchanged

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

  • minSizeOptional

    number

    Machines always on, 0 to 200, not above maxSize (400); omitted: unchanged

    Constraints: integer, 0-200

  • maxSizeOptional

    number

    Most machines at once, 1 to 200; omitted: unchanged

    Constraints: integer, 1-200

  • spareOptional

    number

    Idle machines kept above demand, 0 to 50; omitted: unchanged

    Constraints: integer, 0-50

  • cleanMachinePerJobOptional

    boolean

    true: destroy every machine after its job; false: reuse it within its paid hour; omitted: unchanged

  • shareTrustedMachinesOptional

    boolean

    Let trusted jobs of every repository share machines (pull request jobs never do); omitted: unchanged

  • prebuiltImageOptional

    boolean

    Boot from the organization's pre-built runner image (true) or stock Ubuntu (false); machines already running keep theirs; omitted: unchanged

  • placementOptional

    enum

    own-hosts-first or cloud-only; machines already running stay where they are; omitted: unchanged

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

Response

200 with the pool as the list shows it. New minSize and maxSize also go to its auto scaling group, and the pool is rescaled at once; a prebuiltImage change reaches the launch template on the next scaling pass. 400 when the body is empty, minSize ends up above maxSize, or a label is a macOS label; 404 when the pool is not in this organization.

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:UpdateRunnerPool 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 update id

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_update.