---
title: Deploys
description: What a push starts — the build, the Release, the waves, the rollback, and the preview every pull request gets.
type: how-to
product: hosting
summary: How code reaches production, and how to undo it.
updated: 2026-10-01
order: 0
---

A deploy is not a command. A push to the branch a Service ships from is read
by the platform, built, released and rolled out — and each of those stages is
something you can watch and, where it matters, stop.

## What a push starts

1. **Source is read at an exact commit.** The project's forge connection
   mints a token narrowed to that one repository; a webhook is only a latency
   hint, never the authority for a build.
2. **Build** turns the commit into an image, and the image is identified by
   its digest from then on.
3. **Release.** A Release is the immutable desired state of the environment's
   workloads. Writing a newer Release supersedes the live one; it is never
   edited.
4. **Rollout.** The new generation is served to the Cell that runs your
   Service. Waves — a canary Cell, one Cell, one region, all — are planned:
   one Cell answers today, so there is no canary ring to wait on yet. The
   generation is still checked at the moment of write, and a stale one is
   refused.

<Callout tone="note" title="Today this runs on the management API">
Deploys run on the management API, and every call on this page is served there. The `service_rollouts`, `previews` and `source_links` collections in the [API reference](/docs/api/service_rollouts) are a different, collection-style surface and are not part of this page.
</Callout>

## Watching a deploy

Each environment has a status and a history. Read them with the environment's
id (`env_…`):

```bash
sylphx api GET /v1/deployments/projects/$ENV_ID/status
sylphx api GET /v1/deployments/projects/$ENV_ID/deployments
sylphx api GET /v1/deployments/builds/$BUILD_ID
sylphx api GET /v1/projects/$PROJECT_ID/logs
```

`status` is `running` once the app is live and `unhealthy` when the deploy
failed. A build names its commit, its image and its timing, and the logs say
why a deploy stopped.

## Start one by hand

A push starts a deploy by itself. To start one without a push:

```bash
sylphx api POST /v1/projects/$PROJECT_ID/deploy -d '{"envType":"production"}'
```

`force` rebuilds even when the commit has not changed, and `serviceName`
limits the deploy to one service.

## Redeploy and roll back

A redeploy mints a new Release from the environment's current commit. Pass a
`commit` to go back to a commit that has already been built; one that is not
fully built is refused, and so is a redeploy while another release is in
flight.

```bash
sylphx api POST /v1/projects/$PROJECT_ID/environments/$ENV_ID/deployments/redeploy -d '{"commit":"<sha>"}'
```

<Callout tone="note" title="Rolling back is not a revert">
The Release names older digests, so the code is what it was. The database is
not: migrations that ran since are still applied. [Migrations](/docs/database/migrations)
has the shapes that survive a rollback.
</Callout>

## Pause an environment

Pausing stops new deploys from moving the environment while you investigate:

```bash
sylphx api POST /v1/projects/$PROJECT_ID/environments/$ENV_ID/deployments/pause -d '{"paused":true,"reason":"investigating an incident"}'
```

`{"paused":false,"reason":"…"}` lets deploys move again, and a `GET` on the
same path reads the current state.

## Previews

An environment of type `preview` is where pull-request deploys land. A project
is created with one, and preview databases are branched per environment with
`/v1/projects/$PROJECT_ID/preview-envs/$ENV_ID/branch-db`. Give a preview its
own data — a preview that writes to the production database is a production
deploy with extra steps.

## Custom domains

A domain belongs to a project and is attached to an environment. Add the
domain, then attach a hostname to a service:

```bash
sylphx api POST /v1/projects/$PROJECT_ID/domains -d '{"apexDomain":"example.com","envType":"production"}'
sylphx api POST /v1/projects/$PROJECT_ID/domains/$DOMAIN_ID/hostnames -d '{"hostname":"shop.example.com","serviceId":"$SERVICE_ID","isPrimary":true}'
sylphx api POST /v1/projects/$PROJECT_ID/domains/$DOMAIN_ID/hostnames/$HOSTNAME_ID/check
```

`check` reads the DNS records now. Certificates are issued and renewed once
the hostname is verified. The full walk-through is the
[Network quickstart](/docs/network/quickstart).

## Self-hosted runners

Builds run on platform runners by default. To register your own machines, see
[Runners](/docs/runners/quickstart).

<RelatedDocs
	links={[
		{
			href: '/docs/hosting/health-checks',
			label: 'Health checks',
			description: 'The probe that decides an instance may take traffic.',
		},
		{
			href: '/docs/database/migrations',
			label: 'Migrations',
			description: 'Schema changes that survive a rollout — and a rollback.',
		},
		{
			href: '/docs/hosting/quickstart',
			label: 'Hosting quickstart',
			description: 'A repository to a running app.',
		},
	]}
/>