runner.execution-launch-cloud-run

Launch one runner execution on Cloud Run

Overview

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

Input Schema

Field	Type	Required	Default	Description
runner_group_uuid	uuid	Yes	—	Runner group UUID
organization_uuid	uuid	No	—	Organization UUID (validated against runner group)
runner_execution_uuid	uuid	No	—	Existing execution UUID to reuse
environment	dict	No	—	Environment variables passed to the container. Vaulted (engine >=1.12.0): persisted state_data holds a [VAULT:...] reference, never the values. Still prefer secret_environment for credentials — it keeps them out of the job spec entirely
secret_environment	dict	No	—	Env vars bound to Secret Manager refs (env_var -> secret id or {secret, version}); rendered as secretKeyRef so values stay out of the job spec/audit log
staged_secret_ids	list	No	—	Ephemeral Secret Manager ids minted by runner.execution-secret-stage-gcp for this execution; deleted when the execution goes terminal
command	string	No	—	Command override (generic executions only)
extra_labels	dict	No	—	Additional GCP labels for the Cloud Run job (lowercase keys enforced, e.g. agent-session-id)

Output Schema

Field	Type	Required	Default	Description
runner_execution_uuid	uuid	Yes	—	RunnerExecution row this workflow drove
runner_group_uuid	uuid	No	—	Runner group the execution belongs to
organization_uuid	uuid	No	—	Organization UUID (validated against runner group)
command	string	No	—	Command override (generic executions only)
environment	dict	No	—	Environment variables passed to the container (vaulted — persisted state_data holds a [VAULT:...] reference)
secret_environment	dict	No	—	Env vars bound to Secret Manager refs (secretKeyRef); values stay out of the job spec/audit log
staged_secret_ids	list	No	—	Ephemeral Secret Manager ids minted for this execution; deleted at terminal state
extra_labels	dict	No	—	Additional GCP labels for the Cloud Run job
provider_execution_id	string	No	—	Cloud Run job execution reference
registration_token	string	No	—	GitHub registration token (when applicable)
permission_preflight	json	No	—	GCP IAM permission preflight check result
mirror_tuple	json	No	—	Internal handoff: Cloud Run registry mirror tuple resolved by precheck_mirror and consumed by launch_execution to rewrite the container image path; null when no mirror rewrite is required
completed_at	string	No	—	ISO timestamp when launch finalised
failed_at	string	No	—	ISO timestamp when launch failed
failure_reason	string	No	—	Populated only when the workflow ends in FAILED
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
initiated	Yes	No	—	prepare	—
getting_registration_token	No	No	—	precheck_permissions	—
launching_execution	No	No	—	complete	—
prechecking_mirror	No	No	—	get_registration_token	—
prechecking_permissions	No	No	—	launch_execution	—
preparing	No	No	—	precheck_mirror	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
initiated	prepare	preparing	—
preparing	precheck_mirror	prechecking_mirror	—
prechecking_mirror	get_registration_token	getting_registration_token	—
getting_registration_token	precheck_permissions	prechecking_permissions	—
prechecking_permissions	launch_execution	launching_execution	—
launching_execution	complete	completed	—
* (any state)	fail	failed	—

API Usage

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

{
  "workflow_type": "runner.execution-launch-cloud-run",
  "initial_data": {
    "runner_group_uuid": "value"
  }
}