data.runner.group-persist

Create a new runner group row (UUID-only surface)

Insert a RunnerGroup row from UUID-keyed input.

Designed as a single-state terminal workflow so the engine takes the _run_non_persistent path: only action_done is invoked, no auto_advance chain runs, and the engine never seeds state_data from input_data (which would otherwise leak the input fields into the declared output_schema — see engine.py:_run_non_persistent vs the persistent path that defaults new_state_data = dict(initial_data)).

Overview

Property	Value
Workflow type	Atomic
Library	App-runners
Version	1.0

Input Schema

Field	Type	Required	Default	Description
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 newly persisted RunnerGroup row; chain into runner.group-creation / runner.environment-provision. Also resolvable via the organization's list of runner groups.
created_at	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	Group persisted

API Usage

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

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