Deployments

A deployment is a versioned, immutable build of your project that is running in a specific environment. Every time you push a commit to a tracked branch, or run deploy from the CLI, the platform builds a new deployment, runs your health checks, and then routes traffic to it once it is ready.

Deployment lifecycle

Each deployment moves through the following stages:

Traffic switching is atomic. Requests in flight when the switch happens finish on the old deployment, and new requests go to the new one.

Triggering a deployment

From Git

Connect a repository under Project → Settings → Git. Pushes to the production branch create production deployments. Pushes to any other branch create preview deployments with their own URL.

From the CLI

$ platform login
$ platform deploy --env staging
Uploading 2.4 MB ... done
Deployment dpl_7fK2qW created (queued)
Waiting for live status ... live
https://myapp-staging.example.app

From the API

curl -X POST https://api.example.app/v1/projects/prj_123/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "staging", "ref": "main"}'

The response includes the deployment ID. Poll GET /v1/deployments/{id} to track its status, or subscribe to the deployment.updated webhook event.

Environments and branches

Each project has three built-in environments. You can add more under Environments.

Configuration file

Deployment behavior is controlled by platform.yaml at the root of your repository. Settings here override the dashboard defaults.

build:
  command: npm ci && npm run build
  output: dist

start:
  command: node server.js
  port: 8080

health:
  path: /healthz
  interval: 5s
  timeout: 2s
  healthy_threshold: 2

scale:
  min_instances: 2
  max_instances: 6
  cpu: 0.5
  memory: 512Mi

rollout:
  strategy: blue-green   # or "rolling"
  auto_rollback: true

Health checks

The platform sends GET requests to the health path on each new instance. An instance is considered healthy after healthy_threshold consecutive 2xx responses. If no instance becomes healthy within two minutes, the deployment is marked failed and traffic stays on the previous version.

Rolling back

Because deployments are immutable, rolling back means pointing traffic at an earlier deployment. No rebuild is needed, and it completes in a few seconds.

$ platform deployments list --env production
ID            STATUS      CREATED
dpl_7fK2qW    live        2 minutes ago
dpl_4mXc9R    superseded  3 hours ago
dpl_1aBnT8    superseded  2 days ago

$ platform rollback dpl_4mXc9R --env production
Switching production to dpl_4mXc9R ... live

You can also use the Rollback button on any superseded deployment in the dashboard. Rollbacks are recorded in the audit log.

If auto_rollback is enabled, the platform reverts automatically when the error rate on a new deployment rises above 5% within its first ten minutes.

Deployment statuses

Limits

• Maximum build time: 30 minutes.
• Maximum upload size for CLI deploys: 500 MB.
• Concurrent builds per project: 3 on the free plan, 10 on paid plans.
• Deployments retained per environment: 20. Older deployments beyond this count are pruned, but never the current live one.

See Limits and quotas for the full list.