Deploys

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.

#Watching a deploy

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

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:

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.

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

#Pause an environment

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

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:

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.

#Self-hosted runners

Builds run on platform runners by default. To register your own machines, see Runners.