ci.runner-pools.createCreate a runner pool
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
nameRequiredstring
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}$/
labelsRequiredarray 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}$/
sizeRequiredenum
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-16minSizeOptionalnumber
Machines always on (the base), 0 to 200, not above maxSize (400); 0 when omitted
Constraints: integer, 0-200
maxSizeRequirednumber
Most machines at once, 1 to 200
Constraints: integer, 1-200
spareOptionalnumber
Idle machines kept above demand, 0 to 50; 0 when omitted
Constraints: integer, 0-50
cleanMachinePerJobOptionalboolean
Destroy every machine after its job instead of reusing it within its paid hour; off when omitted
shareTrustedMachinesOptionalboolean
Let trusted jobs (default branch, tags, dispatch, schedules) of every repository share machines; pull request jobs never do; off when omitted
prebuiltImageOptionalboolean
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
placementOptionalenum
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-onlyrunnerGroupIdOptionalstring
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 1curl -X POST "https://console.platform.deutschecloud.app/ci/api/runner-pools" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"example","labels":["example"],"size":"s-2","maxSize":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.