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

# How it works

> Understand the five nouns slipway is built from and how they nest.

slipway has five nouns: organization, repository, service, project and deployment. A
project is the thing that runs. Everything else either describes it or records what
happened to it.

```mermaid theme={"system"}
flowchart TD
  O[Organization] --> R[Repository]
  O --> P[Project]
  R -.->|source for| C[Service]
  P --> C
  C --> D[Deployment]
```

## Organization

An organization is your tenancy boundary. It maps one to one with a GitHub App
installation or a GitLab group: installing on an account gives you exactly one slipway
organization. Installing on a second account gives you a second organization.

The organization has an opaque, permanent ID of the form `ws-a1b2c3d4e5f6` that appears
in your console URLs and API paths. Its display name is yours to change at any time
(Settings → General, admin role required), and any number of workspaces can share a
name — the ID is the identity, the name is a label.

## Repository

A repository is a GitHub repo or GitLab project that slipway has ingested. A repository
does not deploy on its own. It becomes deployable when you add it to a project, which
validates its `slipway.yaml` and starts tracking a branch.

## Service

A service is one entry under `services:` in your spec. There are four types.

| Type | Runs | Gets a URL |
| - | - | - |
| `web` | Continuously | Yes, if a port is marked `public: true` |
| `worker` | Continuously | No |
| `cron` | On a schedule | No |
| `static` | Built once, served from the CDN | Yes |

Services in the same project reach each other by bare service name over a private
network, so an API can call `http://postgres:5432` without knowing an address. Service
names are therefore unique within a project.

See [Services](/services/compute) for how a service is sized and
[slipway.yaml](/slipway-yaml/services) for every field.

## Project

A project is the unit that runs. It holds one or more services, drawn from one repository
or several, plus the variables and secrets they resolve against. Deploying a project
brings all of its services up together on one private network.

Every deployment belongs to a project. Deploying a single repository creates a
one-service project for it, so there is one code path rather than two.

See [Projects](/projects/overview).

## Deployment

A deployment is one attempt to bring a commit live. It carries a status, an append-only
event log, and a map of the public URLs it produced.

```
queued → building → deploying → healthy
                                  ↓
                              superseded   a newer deploy for the same branch went live
                              cancelled    you cancelled it, or a newer commit took over
                              failed       the build, the deploy or the health check did not succeed
```

A healthy service can also enter `sleeping` and `resuming` if sleep on idle is turned on.
Every transition appends an event, which the console renders as a phase ladder. See
[Statuses and events](/reference/statuses-and-events).

## Supersession

When a new commit lands on a branch that already has a deployment, slipway cancels any
in-flight deploy for that branch, builds the new commit, and marks the previous
deployment `superseded` once the new one is healthy.

The public hostname does not change across commits. Traffic moves to the new build at
cutover, and the old pods are removed after it.

## Appendix: glossary

| Term | Meaning |
| - | - |
| Apps base domain | The parent zone public services are served under, giving each one `<service>.<apps-base>`. See [Custom domains](/networking/domains) to use your own. |
| Cutover | The moment a public URL starts serving a new build. |
| Probe | A startup, readiness or liveness check declared in `healthcheck:`. One of `http`, `tcp`, `exec` or `grpc`. |
| Resolution | Expanding every `${secret.*}`, `${var.*}` and `${service.*}` reference to a value at deploy time. An unresolvable secret/variable reference warns and leaves the key unset; only the compose `${NAME:?}` required form fails the deploy. |
| Snapshot | A point-in-time copy of a [disk](/data/disks), taken on a schedule or on demand. |
| Supersession | Marking a previous deployment as replaced once a newer one is healthy. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.