Build Lifecycle & UX

Build state machine:

stateDiagram-v2
  direction LR
  [*] --> pending
  pending --> building
  building --> built
  built --> deploying
  deploying --> deployed
  pending --> cancelled
  building --> failed
  built --> cancelled
  deploying --> failed
  deployed --> [*]
  failed --> [*]
  cancelled --> [*]

  classDef ok fill:#0EAB5D22,stroke:#0EAB5D,color:#0EAB5D
  classDef alert fill:#EC385622,stroke:#EC3856,color:#EC3856
  classDef muted fill:transparent,stroke:#808080,color:#808080
  class deployed ok
  class failed alert
  class cancelled muted

Diagram — Build state machine (§16.12). Happy path pending → building → built → deploying → deployed; failed and cancelled are terminal (previous version stays live).

State transitions:

State	Meaning
pending	build job enqueued, not yet picked up by worker
building	Depot has accepted the build; Starbase Worker streaming logs
built	image pushed to DO Container Registry, image ref recorded
deploying	desired state updated; Shuttle detecting and applying
deployed	Shuttle reports at least one healthy pod running the new image
failed	terminal; error message recorded; previous version remains live
cancelled	terminal; user-initiated or superseded by debounce

Progress visibility:

The dashboard surfaces four distinct progress stages for each deployment, each with its own log stream and timing:

1. Clone — source fetch from Git (typically <10s)
2. Build — Depot-executed build with Railpack/Dockerfile (30s–5min)
3. Push — image push to DO Container Registry (10–60s)
4. Deploy — Shuttle rollout with readiness checks (30s–2min)

Total target: <5 minutes for typical applications.

User-initiated cancellation:

• Customer clicks "Cancel" during pending, building, or deploying states
• Starbase calls BuildService.CancelBuild (Depot stops the build)
• Starbase updates state to cancelled; no charge for the build
• If cancel arrives during deploying, Shuttle is signaled to stop mid-rollout; previous ReplicaSet kept (no rollback needed; new one never fully rolled out)

Post-deploy credential display:

After a database or bucket is successfully provisioned, the service detail page displays connection strings and credentials in a "Connection Info" panel. This is environment-scoped and subject to RBAC (§15) — Developers see full creds in non-protected envs; in protected envs they see masked values unless they have Project Admin role.

---

Cross-references

The built → deploying handoff to Shuttle's reconcile loop → §16.2 · the BuildService.CancelBuild contract → §16.3 · debounce that supersedes a build into cancelled → §16.11 · the RBAC roles gating credential display → Foundations §15 · the desired-state update behind deploying → Foundations §32.