Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.slipway.sh/llms.txt

Use this file to discover all available pages before exploring further.

​
Status state machine

Both convoys and instances share the same status enum. 
creating       → row exists; no deploy fan-out yet
deploying      → one or more component deployments in flight
healthy        → every component's latest deployment is healthy. TTL clock starts here.
degraded       → at least one component failed but ≥ 1 is healthy. Siblings keep serving.
failed         → every component failed on first deploy.
tearing_down   → teardown initiated; namespaces being deleted
torn_down      → all namespaces gone; row stays for history
degraded is a soft state — a redeploy of the failing component flips the convoy or instance back to healthy.

​
Convoy primary instance

A convoy with enable_primary_instance=false is a pure definition. It has a row, components, vars, secrets — but no live deployment until a PR spawns an instance. Calling Deploy on a definition-only convoy errors with "convoy <id> has no primary instance". With enable_primary_instance=true, the convoy itself runs at the tracked refs. Pushes to a tracked branch auto-redeploy the matching component in the primary instance (component-level autoRedeploy must also be on).

​
PR instance lifecycle

PR opened          → spawn instance, deploy
PR synchronize     → redeploy triggering component only (siblings stay frozen)
PR closed          → teardown
operator "Refresh" → re-resolve siblings to parent convoy's tracked-ref HEAD and redeploy
The triggering component is the one whose repo had the PR. Siblings are the other components in the instance — they’re pinned to the SHA they were spawned with so a PR preview is reproducible until the operator explicitly refreshes.

​
TTL

When a convoy is created with ttlSeconds, the clock starts when the convoy or instance reaches healthy — not at create time. Build/deploy time doesn’t eat into the user’s preview window. Convoy TTLs apply to the primary instance; instances inherit the convoy’s TTL unless overridden. When the timer fires, the env is torn down via the standard teardown path.

​
Refresh

The Refresh action on an instance detail page:
  1. Loads the parent convoy’s components for the source-of-truth tracked refs.
  2. For every sibling component in the instance (i.e., not the triggering one), rewrites its ref_value to the parent’s current tracked ref.
  3. Redeploys those siblings against the freshly resolved HEAD SHA.
  4. Leaves the triggering component untouched — that’s the PR’s territory.
Useful when sibling main has moved on since the PR was opened and the reviewer wants the preview to pick up the latest baseline.

​
Teardown

DELETE /api/orgs/<slug>/environments/<envId> (or Teardown from the detail page):
  1. Flips status to tearing_down.
  2. Supersedes every in-flight component deploy.
  3. Deletes every namespace labelled slipway.io/environment=<envId>.
  4. Flips status to torn_down. Row + log persist.
For a convoy with active PR instances, tearing down the convoy doesn’t cascade to the instances — they’re independent rows. Teardown each instance separately (or just close the PRs; that tears them down naturally).

​
Cancellation semantics

When you cancel an individual deployment that’s part of a convoy or instance, slipway:
  • Marks the Deployment row cancelled.
  • Does NOT tear down the component’s namespace — it’s shared with the previous successful deploy.
This differs from standalone single-repo deployments, where cancellation tears the namespace down.