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.

An environment is defined by its components — the (repo, ref, slug) tuples it composes. This page covers how composition behaves at deploy time.

​
Component slugs

Every component carries a DNS-safe slug (^[a-z][a-z0-9-]{0,31}$). The slug:
  • defaults to the repo name on create, but the operator can override (frontend-v2 vs the repo’s actual frontend).
  • must be unique within the env (enforced by the API).
  • is used as the URL prefix and the SL_<COMPONENT>_* env var prefix every other vessel sees.
You’d override the default when:
  • Two repos export a service called api and you need them to coexist (set component slugs frontend-api and core-api, or rename the slugs themselves).
  • You want a more readable URL than the repo name (acme-cms repo, but you want cms in the hostname).

​
Ref kinds

Convoys track refs (the long-lived target) — PR instances clone the convoy and override one component to the PR’s HEAD branch automatically.
Ref kindWhat slipway tracksWhen the primary instance redeploys
branchLatest SHA on the named branchOn every push to that branch (if autoRedeploy is on)
tagLatest SHA the tag points atOn every push that moves the tag
commitAn exact SHA, immutableNever auto-redeploys — pin for snapshots
A component can mix branches and tags freely (frontend on main, payments on tag:v2.4.0). Each is resolved to a SHA at deploy time via the GitHub API. There is no pr ref kind in the composer — PR previews are handled by the per-PR instance flow. See webhooks.

​
Spec path overrides

Each component reads the spec from its repo’s default slipway.yaml. For monorepos, override per component:
  • Repo mono-svc, component web, spec path apps/web/slipway.yaml
  • Repo mono-svc, component api, spec path apps/api/slipway.yaml
Both components pull from the same repo, the same commit, but resolve different specs.

​
Cross-service DNS

When a deploy lands, slipway injects sibling URLs into every service’s environment: 
SL_<COMPONENT_SLUG>_<SERVICE>_URL    e.g. SL_API_SERVER_URL=http://api-server.sl-envcomp-…svc:8080
SL_<COMPONENT_SLUG>_<SERVICE>_HOST   e.g. SL_API_SERVER_HOST=api-server.sl-envcomp-…svc
SL_<COMPONENT_SLUG>_<SERVICE>_PORT   e.g. SL_API_SERVER_PORT=8080
SL_<COMPONENT_SLUG>_<SERVICE>_PUBLIC_URL   only when the service has a public port
Inside the same component (siblings sharing a namespace), services also get a short form: 
SL_<SERVICE>_URL    e.g. SL_REDIS_URL inside the same component
Names are uppercased and hyphens become underscores. User-supplied env: values always win — if your slipway.yaml sets API_URL explicitly, slipway won’t overwrite it.

​
When a peer hasn’t deployed yet

Sibling injection only includes peers that have at least one healthy deployment. On a fresh convoy, the first deploy pass injects only same-component siblings; the next redeploy of any peer fills in the cross-component refs. This is by design — we’d rather show an empty SL_API_SERVER_URL than point at a service that 502s.

​
URL pattern

https://<env-slug>-<component-slug>-<port-prefix>.<apps-base-domain>
  • env-slug — set when the convoy was created, immutable.
  • component-slug — the component’s slug, immutable.
  • port-prefix — either the explicit prefix: from the service’s ports entry, or the service name when no prefix is set.
The full hostname is stable across redeploys of the same component — bookmarks and PR comments don’t churn.

​
Naming collisions

If two components both expose a service named api and both want a public port, the host pattern alone won’t collide (each component has its own slug prefix), and each component lives in its own namespace so internal Service/Deployment object names don’t collide either. The only collision the operator has to think about is the component slug itself, which the API rejects with a clear error at create-time.