runner.group-creation.prepare

Ensure the runner group row exists (create it from the domain inputs when no runner_group_uuid is supplied), validate cloud + GitHub connections, and publish routing keys for the creation DAG

Validate connections and publish routing keys for the creation DAG.

Overview

Property	Value
Workflow type	Atomic
Library	App-runners
Version	1.0

Input Schema

Field	Type	Required	Default	Description
`runner_group_uuid`	uuid	No	—	UUID of an EXISTING RunnerGroup to provision. Omit to create a brand-new group from the fields below (name, backend_type, cloud_connection_uuid, …): this workflow persists the row itself and then provisions it. Supply it only to (re)provision a group that already exists — e.g. after runner.group-creation-abort.
`organization_uuid`	uuid	Yes	—	UUID of the caller's organization, injected server-side from the authenticated request; scopes the operation to the correct tenant.
`name`	string	Yes	—	Human-readable runner group name, unique per organization (and among non-deleted groups). Used to label the group and derive cloud resource names.
`backend_type`	string	Yes	—	Compute backend that runs this group's runners. One of: devkit, fargate, ec2_auto_scaling, ec2_vm, gce, cloud_run, kubernetes, eks, azure_container_apps_job, azure_vm, azure_vmss, do_app_job, do_droplet, mgc_vm. Determines which cloud connection and config keys are required — call data.runner.list-provider-config-specs for the config keys per backend.
`purpose`	string	Yes	—	What the runners are for. One of: github_actions, gitlab_runner, generic, agent. Use 'agent' to host Orkestia agent sessions; 'generic' for plain container jobs with no CI integration.
`integration_type`	string	Yes	—	CI system this group registers runners with. One of: github, gitlab, none. 'github' requires github_installation_uuid; 'gitlab' requires gitlab_connection_uuid (+ project/group target); 'none' registers no external CI runner.
`runner_scope`	string	Yes	—	Scope the runners are registered at. One of: organization, repository. 'repository' (GitHub only) requires github_repository_uuid.
`cloud_connection_uuid`	uuid	No	—	UUID of the CloudConnection backing provider-backed runner groups. Required for cloud backends; omit for backend_type=devkit.
`network_profile_uuid`	uuid	No	—	UUID of the NetworkProfile bound to this runner group, picked from the organization's network profiles. Optional — omit when absent.
`registry_account_uuid`	uuid	No	—	UUID of the container registry account this runner group resolves images against, picked from the organization's registry accounts. Optional — falls back to default/unauthenticated image resolution when absent.
`image_pull_cloud_connection_uuid`	uuid	No	—	UUID of the CloudConnection used to authenticate image pulls for this runner group, picked from the organization's connections. Optional — falls back to cloud_connection_uuid when absent.
`github_installation_uuid`	uuid	No	—	UUID of the GitHub App installation bound to this runner group's GitHub integration. No list/query workflow exists in the platform today (data.github.installation.list has not been built), so this value must be supplied directly by the caller; omit when absent.
`github_repository_uuid`	uuid	No	—	UUID of the GitHub repository this runner group is scoped to, picked from repositories under the organization. Optional — omit when absent (only set for repository-scoped groups).
`gitlab_connection_uuid`	uuid	No	—	UUID of the GitLab CloudConnection bound to this runner group, picked from the organization's GitLab connections. Optional — omit when absent (only set for GitLab-integrated groups).
`gitlab_project_uuid`	uuid	No	—	UUID of the GitLab project this runner group is scoped to. No list/query workflow exists in the platform today (data.gitlab.project.list has not been built), so this value must be supplied directly by the caller; omit when absent.
`gitlab_target_kind`	string	No	—	—
`gitlab_group_path`	string	No	—	—
`region`	string	No	—	Cloud region the runners are provisioned in (e.g. 'us-east-1' for AWS). Required for all cloud backends (aws/gcp/azure/digitalocean/mgc); omit only for bring-your-own kubernetes.
`desired_count`	integer	No	1	—
`min_count`	integer	No	0	—
`max_count`	integer	No	10	—
`description`	string	No	—	—
`runner_labels`	list	No	—	—
`config`	dict	No	—	Backend-specific settings (e.g. ecs_cluster_name for Fargate, machine_type for GCE, container_image). Required keys vary by backend_type — call data.runner.list-provider-config-specs to get the exact keys before creating.
`coding_runtime_enabled`	boolean	No	—	Enable the software-development-v1 runtime profile for this agent runner group. Requires a customer storage connection; runner.group-creation provisions and binds the private artifact bucket through the Storage workflow.
`coding_artifact_storage_connection_uuid`	uuid	No	—	Customer CloudConnection used by the Storage workflow to provision private coding-artifact storage.
`coding_artifact_retention_days`	integer	No	—	Recovery retention for noncurrent artifact versions, between 7 and 90 days.
`coding_artifact_capacity_bytes`	integer	No	—	Required hard live-byte ceiling for the customer-owned coding-artifact bucket. Valid range: 512 MiB to 1 TiB.
`coding_artifact_storage_usd_per_gb_month`	string	No	—	Customer storage price in USD per decimal GB-month, passed only to the Storage-owned provisioning workflow.
`coding_artifact_storage_pricing_revision`	string	No	—	Immutable revision identifier for the supplied storage price.
`auth_type`	string	No	—	—
`actor_uuid`	uuid	No	—	UUID of the user or service actor who triggered this action, injected server-side from the authenticated request; used for audit/attribution only. Optional — omit for system or service-triggered actions with no human actor.

Output Schema

Field	Type	Required	Default	Description
`runner_group_uuid`	uuid	No	—	UUID of the RunnerGroup this action operates on, picked from the organization's list of runner groups; echoed on output alongside terminal/error payloads.
`organization_uuid`	uuid	No	—	UUID of the caller's organization, injected server-side from the authenticated request; scopes the operation to the correct tenant. Echoed on output alongside terminal/error payloads.
`runner_execution_uuid`	uuid	No	—	UUID of the RunnerExecution this action operates on, picked from the organization's (optionally group-scoped) list of executions; echoed on output alongside terminal/error payloads.
`workflow_uuid`	string	No	—	Engine workflow-run identifier (or, for GitHub-Actions-triggered flows, an external GitHub Actions run id) associated with this record; not a platform entity foreign key despite the name. No source is attached since there is no list/query workflow for an internal run id.
`status`	string	No	—	—
`outcome`	string	No	—	—
`initiated_at`	string	No	—	—
`completed_at`	string	No	—	—
`failed_at`	string	No	—	—
`failure_reason`	string	No	—	—
`error`	string	No	—	—
`error_type`	string	No	—	—
`actor_uuid`	uuid	No	—	UUID of the user or service actor who triggered this action, injected server-side from the authenticated request when available; used for audit/attribution only. Optional — omitted for system or service-triggered actions with no human actor.
`reason`	string	No	—	—
`workflow_run_uuid`	string	No	—	Engine-stamped correlation/run id for this DAG execution (ADR-015/E1 plumbing), written into state_data by `action_start`; not a foreign key to any business entity. No source is attached since there is no list/query workflow for an internal run id.
`retry_count`	integer	No	—	—
`retried_from`	string	No	—	—
`failed_step`	json	No	—	—
`failed_layer`	json	No	—	—
`failed_at_state`	json	No	—	—
`compensation_trigger`	json	No	—	—
`comp_current_layer`	json	No	—	—
`comp_queue`	json	No	—	—
`comp_retry_count`	json	No	—	—
`backend_type`	string	No	—	—
`runner_group_name`	string	No	—	—
`registry_account_uuid`	uuid	No	—	UUID of the container registry account this runner group resolves images against, picked from the organization's registry accounts. Omitted when the group uses default/unauthenticated image resolution.
`integration_type`	string	No	—	—
`hosted_coding_pool_refresh_required`	boolean	No	—	—
`created_at`	string	No	—	—
`name`	string	No	—	Human-readable runner group name, unique per organization (and among non-deleted groups). Used to label the group and derive cloud resource names.
`purpose`	string	No	—	What the runners are for. One of: github_actions, gitlab_runner, generic, agent. Use 'agent' to host Orkestia agent sessions; 'generic' for plain container jobs with no CI integration.
`runner_scope`	string	No	—	Scope the runners are registered at. One of: organization, repository. 'repository' (GitHub only) requires github_repository_uuid.
`cloud_connection_uuid`	uuid	No	—	UUID of the CloudConnection backing provider-backed runner groups. Required for cloud backends; omit for backend_type=devkit.
`network_profile_uuid`	uuid	No	—	UUID of the NetworkProfile bound to this runner group, picked from the organization's network profiles. Optional — omit when absent.
`image_pull_cloud_connection_uuid`	uuid	No	—	UUID of the CloudConnection used to authenticate image pulls for this runner group, picked from the organization's connections. Optional — falls back to cloud_connection_uuid when absent.
`github_installation_uuid`	uuid	No	—	UUID of the GitHub App installation bound to this runner group's GitHub integration. No list/query workflow exists in the platform today (data.github.installation.list has not been built), so this value must be supplied directly by the caller; omit when absent.
`github_repository_uuid`	uuid	No	—	UUID of the GitHub repository this runner group is scoped to, picked from repositories under the organization. Optional — omit when absent (only set for repository-scoped groups).
`gitlab_connection_uuid`	uuid	No	—	UUID of the GitLab CloudConnection bound to this runner group, picked from the organization's GitLab connections. Optional — omit when absent (only set for GitLab-integrated groups).
`gitlab_project_uuid`	uuid	No	—	UUID of the GitLab project this runner group is scoped to. No list/query workflow exists in the platform today (data.gitlab.project.list has not been built), so this value must be supplied directly by the caller; omit when absent.
`gitlab_target_kind`	string	No	—	—
`gitlab_group_path`	string	No	—	—
`region`	string	No	—	Cloud region the runners are provisioned in (e.g. 'us-east-1' for AWS). Required for all cloud backends (aws/gcp/azure/digitalocean/mgc); omit only for bring-your-own kubernetes.
`desired_count`	integer	No	1	—
`min_count`	integer	No	0	—
`max_count`	integer	No	10	—
`description`	string	No	—	—
`runner_labels`	list	No	—	—
`config`	dict	No	—	Backend-specific settings (e.g. ecs_cluster_name for Fargate, machine_type for GCE, container_image). Required keys vary by backend_type — call data.runner.list-provider-config-specs to get the exact keys before creating.
`coding_runtime_enabled`	boolean	No	—	Enable the software-development-v1 runtime profile for this agent runner group. Requires a customer storage connection; runner.group-creation provisions and binds the private artifact bucket through the Storage workflow.
`coding_artifact_storage_connection_uuid`	uuid	No	—	Customer CloudConnection used by the Storage workflow to provision private coding-artifact storage.
`coding_artifact_retention_days`	integer	No	—	Recovery retention for noncurrent artifact versions, between 7 and 90 days.
`coding_artifact_capacity_bytes`	integer	No	—	Required hard live-byte ceiling for the customer-owned coding-artifact bucket. Valid range: 512 MiB to 1 TiB.
`coding_artifact_storage_usd_per_gb_month`	string	No	—	Customer storage price in USD per decimal GB-month, passed only to the Storage-owned provisioning workflow.
`coding_artifact_storage_pricing_revision`	string	No	—	Immutable revision identifier for the supplied storage price.
`auth_type`	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
`pending`	Yes	No	—	`execute`	—
`completed`	No	Yes	Yes	—	—
`failed`	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
`pending`	`execute`	`completed`	—
`*` (any state)	`fail`	`failed`	—

API Usage

bash

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "runner.group-creation.prepare",
  "initial_data": {
    "organization_uuid": "value",
    "name": "value",
    "backend_type": "value",
    "purpose": "value"
  }
}

runner.group-creation.prepare ​

Overview ​

Input Schema ​

Output Schema ​

States ​

State Diagram ​

Transitions ​

API Usage ​