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.

Six concepts cover almost everything you’ll do in slipway.

​
Organization

An organization is the tenancy boundary in slipway. It corresponds 1:1 with a GitHub installation: when you install the GitHub App on a user or org, you get exactly one slipway organization. Org URLs use a slug derived from the GitHub account login: /{slug}/repos, /{slug}/deployments, and so on. Slugs are immutable.

​
Repository

A repository is a GitHub repo that has been ingested through an installation. Each one carries a flag — slipway_enabled — that controls whether pushes and PRs trigger deployments. Toggling Enable in the UI flips that flag after re-validating the repo’s slipway.yaml on the default branch.

​
Service

A service is a container in your slipway.yaml. Every service produces one Kubernetes Deployment; services with ports: also get a Service, and services with public: true ports get an Ingress. A typical app has one service. A typical full-stack app has two or three (web, api, worker). Services run in the same tenant namespace and can talk to each other over the cluster network.

​
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. Statuses move through: 
queued → building → deploying → healthy
                                ↓
                              superseded   (a newer deploy for the same branch is live)
                              cancelled    (you cancelled, or a newer commit superseded mid-build)
                              failed       (build, deploy, or healthcheck didn't succeed)
Every transition appends a row to the deployment event log, which the UI renders as a phase ladder and the API streams over SSE. See the statuses reference and event kinds reference.

​
Ephemeral

A deployment can be ephemeral — created with a TTL (default 5 minutes for manual deploys). The TTL clock starts when status flips to healthy, not when the deploy was created, so slow builds don’t eat into your preview window. When the TTL elapses, slipway tears the tenant namespace down and marks the deployment superseded. PR-driven and push-driven deployments are not ephemeral. They live until superseded by a newer commit (push) or torn down on PR close (PR).

​
Supersession

When a new commit lands for the same branch or PR, slipway:
  1. Cancels any in-flight deployment for that branch/PR.
  2. Builds the new deployment.
  3. On healthy, marks the previous healthy deployment for the same branch as superseded.
For PR previews, the public hostname (web-pr-42.<apps>) is stable across commits — reviewers’ bookmarks don’t break. nginx-ingress hands the hostname over to the new tenant namespace at cutover.

​
What’s intentionally not modeled

A few things slipway deliberately leaves out — they belong elsewhere or aren’t a fit for ephemeral previews. The full list of “what’s not in the spec and why” lives in the validation page.