Skip to content

Workflow — Preview environment

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
Workflow id preview-environment · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator developer-sandbox-coordinator · family ChatOps, Runtime Commands, Developer Experience
Owner service WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on ChangeProposalOpened from PipelineExecutionService (event)
Steps 5 · gated 1 · agents 2
Budget per run 600000 tokens · cap 60.0 USD · 240 min
Descriptor workflow-definition-v1 · schema
Status target

Creates a per-developer preview environment from a change proposal, keeps it for its time to live and tears it down; a later capability of Runtime Cloud exposed as a workflow.

Authored design, Draft (D54, D57)

These definitions were authored on 2026-10-14 from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.

Definition

flowchart TD
    start(("ChangeProposalOpened"))
    resolve_change["Resolve the change"]
    approve_preview(["Approve the preview"])
    request_preview["Request the preview environment"]
    time_to_live(("Time to live"))
    teardown>"Tear down"]
    start --> resolve_change
    resolve_change --> approve_preview
    approve_preview --> request_preview
    request_preview --> time_to_live
    time_to_live --> teardown
    done(("WorkflowRunCompleted"))
    teardown --> done
    class approve_preview gated
    classDef gated stroke:#B45309,stroke-width:2px
Hold "Alt" / "Option" to enable pan & zoom

Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step.

Steps

# Step Kind Runs Gate Class Depends on Retry Timeout Compensation What it does
1 Resolve the change
resolve-change		 agent environment-manager none read — exponential ×2 PT30M — Resolves the proposal to a buildable change set and the modules it touches.
2 Approve the preview
approve-preview		 human engine approval shared-write resolve-change none P2D — Approval when the project policy gates non-production environment creation.
3 Request the preview environment
request-preview		 agent devops-engineer none shared-write approve-preview exponential ×2 PT30M request the teardown Requests a preview environment with the change set deployed through RuntimeEnvironmentService.
4 Time to live
time-to-live		 timer engine none sandbox request-preview none P3D — Keeps the environment for the configured time to live, extended by use.
5 Tear down
teardown		 compensation engine none sandbox time-to-live fixed ×2 PT30M — Requests the teardown and records the environment's lifetime and cost.

Gates and approvals

  • shared-write: creation of a non-production environment when the project policy requires it (D21) Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).

Inputs, outputs and events

Direction Name Descriptor
in change-proposal pull-request-proposal-v1
out preview-environment artifact-v1

Starts on ChangeProposalOpened; emits EnvironmentCreated, PromotionRequested, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).

Decisions and traceability

FR: FR-09 Usage reservations and reconciliationXL: XL-12 Cost visibility and limitsADRs: ADR-0014, ADR-0017 · ADR index

Definition authored 2026-10-14 from the coordinator card developer-sandbox-coordinator (D54); Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release.