Deployment Lifecycle

A deployment is a state machine driven by a background worker. This page walks every status in order — what it means, what triggers the transition, and what happens when things go wrong.

Starting a deployment (dashboard Deploy button, deplo in the CLI, or POST /deployments directly) creates a deployment record and enqueues an analysis job. From there a worker drives the record through the pipeline while the dashboard and CLI poll for status and logs:

GitHub repository

you pick a repo and branch

PENDING

record created, analysis job enqueued

ANALYZING

detection engine reads the repo tree

WAITING_FOR_ENV

only if required variables are missing — parked until you provide them

DEPLOYING_BACKEND

Render web service in your workspace

BACKEND_READY

backend live — its URL is now known

DEPLOYING_FRONTEND

Vercel build with the backend URL injected

COMPLETED

both URLs recorded, success email sent

Production URLs

…-web.vercel.app + …-api.onrender.com

Note

The backend always deploys first. Its live URL is wired into the frontend build (so the frontend never ships pointing at a URL that does not exist), and the backend receives FRONTEND_URL for CORS. Frontend-only and backend-only repos simply skip the phases they do not need.

Status reference#

Status	Meaning	Leaves when
PENDING	Deployment record created; the analysis job is queued but not yet picked up.	The worker starts analysis.
ANALYZING	The detection engine is reading the repository tree, detecting the stack, and scanning env vars.	Analysis finishes — to `WAITING_FOR_ENV` or `DEPLOYING_BACKEND`.
WAITING_FOR_ENV	Required environment variables have no value. The deployment is parked; nothing deploys.	You provide the missing values (dashboard or `POST /deployments/:id/env`).
DEPLOYING_BACKEND	Creating or reusing the Render web service in your workspace and waiting for its build.	Render reports the service live.
BACKEND_READY	The backend is live and its URL is recorded — the value to wire into the frontend is now known.	The frontend phase begins.
DEPLOYING_FRONTEND	Repository files are uploaded to Vercel and the frontend build runs in your account.	Vercel reports the deployment ready.
COMPLETED	Terminal. Production URLs recorded; success email sent; monitoring picks the project up.	—
FAILED	Terminal. The error and an AI diagnosis are in the logs; a failure email was sent.	— (start a new deployment to retry)
CANCELLED	Terminal. You cancelled the deployment (`DELETE /deployments/:id`) before it finished.	—

Phase 1 — analysis#

The worker sets ANALYZING and runs the detection engine over one snapshot of the repo tree: frameworks, monorepo paths, runtimes, build commands, and the environment variables your code actually reads. Values you pre-filled on the configure step are merged into the detected list.

If any required variable is still empty, the status becomes WAITING_FOR_ENV: the log lists exactly which keys are missing, an email nudge goes out, and the deployment waits — indefinitely, at no cost — until you provide values. If everything required is satisfied, the deploy job is enqueued immediately and analysis flows straight into DEPLOYING_BACKEND.

Phase 2 — backend to Render#

The orchestrator resolves your Render API key (decrypted just-in-time), then creates — or, on a retry or redeploy, finds and reuses — a web service named after your repo, e.g. deplo-my-app-api, in your own workspace on the free plan:

Node backends: build and start commands come from the repo's own package.json scripts and detected package manager (npm, yarn, pnpm, or bun) — never guessed.
Python and Go backends: commands were resolved during analysis from real files (requirements, app modules, go.mod layout).
Env vars: the service receives backend-scoped and shared variables — never frontend-only ones — plus FRONTEND_URL pointing at the frontend's predicted stable domain, so CORS works without a chicken-and-egg problem.

When Render reports the deploy live, the URL (e.g. https://deplo-my-app-api.onrender.com) is stored and the status becomes BACKEND_READY.

Phase 3 — frontend to Vercel#

The orchestrator downloads the frontend's files from GitHub (only the frontend directory in a monorepo) and deploys them file-based to a Vercel project in your account, e.g. deplo-my-app-web, using Vercel's framework preset where one exists. The live backend URL is injected into every frontend key your code references — NEXT_PUBLIC_API_URL, VITE_API_URL, REACT_APP_API_URL, whichever were detected:

deployment log (excerpt)

Backend live at https://deplo-my-app-api.onrender.com
Deploying frontend to Vercel (214 files)…
Wiring frontend → backend: NEXT_PUBLIC_API_URL = https://deplo-my-app-api.onrender.com
Vercel deployment triggered (dpl_4Yx…). Waiting for build…
Frontend live at https://deplo-my-app-web.vercel.app
Deployment completed successfully.

Vercel project names are globally unique, so after the build the orchestrator verifies the actually assigned production domain rather than trusting the prediction. If it differs, the backend's FRONTEND_URL is corrected automatically and a backend redeploy is triggered so CORS stays right.

On COMPLETED, both URLs are final, a success email goes out with the links, uptime monitoring starts probing the project every five minutes, and — where configured — a GitHub webhook is registered (best-effort, never fails the deployment).

When a deployment fails#

Any error in any phase moves the deployment to FAILED with the error message recorded and FAILED: … appended to the log. Then two things happen:

AI diagnosis. One bounded AI call analyzes the detected stack, the error, and the log tail, and appends its findings to the deployment log: the likely cause, whether the stack looks misidentified, corrected build/start/output suggestions where applicable, and a recommendation. If AI is unavailable, the raw error and logs are still all there.
Failure email. You get an email with the explanation and a copy-paste fix prompt for your AI coding tool.

Transient infrastructure errors never reach FAILED on the first hiccup — queue jobs retry up to three times with exponential backoff. Only permanent errors (provider 4xx responses, missing configuration) fail immediately. To retry after a failure, fix and push, then deploy again: existing Render services and Vercel projects are reused idempotently, phases that already completed are skipped (recorded URLs are preserved), and env vars are kept.

Cancellation and rollbacks#

You can cancel a deployment that has not finished (DELETE /deployments/:id or the dashboard) — it moves to CANCELLED and terminal states are never overwritten. Rollbacks to a previous deployment Planned are not implemented yet; today the way back is deploying the previous commit, or using Vercel's and Render's own rollback tools directly — the deployments are in your accounts, so their native tooling always works.

Deployments guide — the same pipeline from a user's point of view.
Environment Variables — scopes, detection, and the WAITING_FOR_ENV flow in detail.
Deployments API — start, poll, provide env, cancel.
Troubleshooting — common failure causes and fixes.