> ## 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.

# Core concepts

> How slipway thinks about deployments.

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](#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](/reference/statuses).

## 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](#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](/environments/overview).

## 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

| Term                 | Meaning                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Apps base domain** | The parent zone previews are served under by default: `<env>-<service>-<id>.<apps-base>`. Bring your own under [Custom domains](/configuration/domains). |
| **Cutover**          | The moment a public URL starts serving the new build.                                                                                                    |
| **Dev instance**     | An ephemeral copy of an environment spun up from the [`sw dev up`](/cli/dev-instances) CLI to test a branch. Reaped when the CLI exits.                  |
| **Primary instance** | An environment's always-on instance — no TTL, watches its tracked refs, auto-deploys on push. Stays up until torn down.                                  |
| **Preview auth**     | Optional gating on public URLs: shared token, GitHub org membership, or a per-deployment token.                                                          |
| **Probe**            | A startup, readiness, or liveness check in `healthcheck:` — one of `http`, `tcp`, `exec`, or `grpc`.                                                     |
| **Resolution**       | Expanding every `${secret.*}` and `${var.*}` reference to its value at deploy time. A missing reference fails the deploy.                                |
| **Snapshot**         | A point-in-time copy of a named [volume](/slipway-yaml/volumes). 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.                                       |