runner.pool-launch-fargate

Launch one warm (non-ephemeral) runner on ECS Fargate and record it as a RunnerInstance. Started by runner.pool-reconcile-fargate when the warm pool is below its floor; the runner stays registered with GitHub and serves multiple jobs until reaped.

Launch one non-ephemeral ECS task and register it as a warm instance.

Overview

Property	Value
Workflow type	Linear
Library	App-runners-aws
Version	1.0

Input Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	Yes	—	UUID of the RunnerGroup this action operates on, picked from the organization's list of runner groups.
organization_uuid	uuid	Yes	—	UUID of the caller's organization, injected server-side from the authenticated request; scopes the operation to the correct tenant.
execution_uuid	uuid	No	—	UUID of an existing RunnerExecution to reuse instead of creating a new one, picked from the group's executions. Optional — a new execution is created when absent.
environment	dict	No	—	Environment variables to pass to container
command	list	No	—	Optional command override for container
runner_image	string	No	—	Optional custom container image for this execution (overrides runner_group config)
github_workflow_run_ref	integer	No	—	GitHub workflow run reference — external GitHub identifier
run_attempt	integer	No	—	GitHub run attempt number — used to build the claim-watch workflow ID for retries
extra_tags	dict	No	—	Additional AWS resource tags to attach to the ECS task (e.g. AgentSessionUuid)

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	—	—
cluster_arn	string	No	—	—
task_arn	string	No	—	—
task_definition_arn	string	No	—	—
log_group_name	string	No	—	—
container_name	string	No	—	—
runner_image	string	No	—	—
needs_custom_image	boolean	No	—	—
registration_token	string	No	—	—
runner_name	string	No	—	—
runtime_env	dict	No	—	—
start_command	list	No	—	—
claim_watch_workflow_uuid	string	No	—	Engine run id of the runner.execution-claim-watch workflow started for this launch, when a github_workflow_run_ref was provided. Internal engine correlation id, not a platform entity foreign key.
last_status	string	No	—	—
execution_uuid	uuid	No	—	UUID of an existing RunnerExecution to reuse instead of creating a new one, picked from the group's executions. Optional — a new execution is created when absent.
command	list	No	—	—
environment	dict	No	—	—
run_attempt	integer	No	—	—
extra_tags	dict	No	—	—
github_workflow_run_ref	integer	No	—	—
runner_instance_uuid	uuid	No	—	UUID of the RunnerInstance created for this warm runner — the long-lived ADR-001 entity the warm-pool controller reconciles against.
warm_pool_launch	boolean	No	—	Always true for this workflow — records that the runner agent was configured non-ephemerally and will serve more than one job.

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	prepare	—
building_start_command	No	No	—	launch_task	—
getting_registration_token	No	No	—	build_start_command	—
launching_task	No	No	—	complete	—
preparing	No	No	—	get_registration_token	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
initiated	prepare	preparing	—
preparing	get_registration_token	getting_registration_token	—
getting_registration_token	build_start_command	building_start_command	—
building_start_command	launch_task	launching_task	—
launching_task	complete	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "runner.pool-launch-fargate",
  "initial_data": {
    "runner_group_uuid": "value",
    "organization_uuid": "value"
  }
}