Skip to main content
A handful of concepts cover everything you’ll do in slipway.

​
Organization

An organization is your tenancy boundary. It maps 1:1 to a GitHub (or GitLab) installation: when you install the app on an account, you get exactly one slipway org. The org has a slug derived from the account login — it shows up in your URLs and never changes.

​
Repository

A repository is a GitHub repo slipway has ingested. A repo deploys once it’s part of an environment (below) — adding it to one validates its slipway.yaml and starts tracking its default branch.

​
Service

A service is one container in your spec. A service with a public port gets its own URL; services in the same deployment can reach each other by name over a private network. A typical app is one service; a full-stack app is two or three (web, api, worker).

​
Deployment

A deployment is one attempt to bring a commit alive. It carries a status, an event log, a public-URL map, and — for ephemeral runs — a TTL. Every deployment belongs to an environment: the environment is the definition of what runs, and the deployment is one live run of it. 
queued → building → deploying → healthy
                                ↓
                              superseded   a newer deploy for the same branch is live
                              cancelled    you cancelled, or a newer commit took over mid-build
                              failed        build, deploy, or healthcheck didn't succeed
Every transition appends to the event log, which the UI renders as a phase ladder. See Statuses & events.

​
Environment

An environment is the blueprint for what runs: which repo (or repos) take part, on which branch, and with which variables and secrets. It ties them together so they deploy as a unit and can talk to each other — a frontend, an API, and a database, brought up side by side. An environment isn’t live on its own. Deploying it produces a deployment — a running copy at its own URL — and one environment can have many deployments over its life (a push, a pull request, a Deploy now). A single enabled repo gets a one-component environment automatically, so every deployment flows through the same path. See Environments.

​
Ephemeral & TTL

A deployment can be ephemeral — created with a TTL (default 5 minutes for manual deploys). The clock starts when the status reaches healthy, not when the deploy was created, so a slow build doesn’t eat your preview window. When it elapses, slipway tears the deployment down. Pull-request and default-branch deployments are not ephemeral. They live until a newer commit supersedes them or the PR closes.

​
Supersession

When a new commit lands for the same branch or PR, slipway cancels any in-flight deploy for it, builds the new one, and — once it’s healthy — marks the previous one superseded. The public hostname stays stable across commits, so reviewers’ links never break; traffic hands over to the newest build the instant it’s healthy.

​
Quick reference

TermMeaning
Apps base domainThe parent zone previews are served under by default: <env>-<service>-<id>.<apps-base>. Bring your own under Custom domains.
CutoverThe moment a public URL starts serving the new build.
Dev instanceAn ephemeral copy of an environment spun up from the sw dev up CLI to test a branch. Reaped when the CLI exits.
Primary instanceAn environment’s always-on instance — no TTL, watches its tracked refs, auto-deploys on push. Stays up until torn down.
Preview authOptional gating on public URLs: shared token, GitHub org membership, or a per-deployment token.
ProbeA startup, readiness, or liveness check in healthcheck: — one of http, tcp, exec, or grpc.
ResolutionExpanding every ${secret.*} and ${var.*} reference to its value at deploy time. A missing reference fails the deploy.
SnapshotA point-in-time copy of a named volume. New previews seed from the latest one.
<id>The short, stable identifier in a preview URL. Every service in one instance shares it, and it survives redeploys.