Skip to content

Deployment lifecycle ​

Two ideas explain most of how Edge behaves.

distribution — owns the URL, outlives every deploymentpendingbundle uploadedreadypreview publishedliveserving visitorscommitlive site untouchedpromotetraffic movesPUT bundle.tar.gzrollbackpreview URL — nobody else has itacme-marketing.edge.deca-dev.com
Commit publishes a preview and leaves the live site alone. Promote is the step that moves traffic — and rollback undoes it.

Distributions and deployments ​

A distribution is the site as an ongoing thing: its name, its slug, its settings, its domains. It owns the URL. It is what you point people at, and it outlives every version of the content.

A deployment is one version of that site's files. A distribution accumulates many deployments over its life, and exactly one of them is live at a time.

This split is why rolling back is cheap. The previous deployment was never deleted when you promoted a new one — it was simply no longer the one being served. Putting it back is a pointer change, not a rebuild.

Commit and promote are deliberately separate ​

Publishing happens in two stages, and it is worth understanding why rather than treating it as ceremony.

Commit hands your uploaded bundle to a worker. The worker unpacks it, publishes the files, and gives the deployment its own preview URL at {deployment_id}.preview.edge.deca-dev.com. When this finishes, the deployment's status is ready and preview_published is true.

Nothing about your live site has changed. Visitors are still being served the previous deployment.

Promote is the step that moves live traffic to the new deployment.

Keeping these apart means the expensive, failure-prone part — unpacking an archive, publishing files, discovering that a build was broken — happens somewhere no visitor can see. By the time you promote, the deployment is already built and serving; promotion only changes which one the public gets.

It also means a preview is a real test rather than an approximation. The preview URL serves the same files the same way the live URL will. If it looks right there, it will look right live.

Status values ​

statusMeaning
pendingCreated, waiting for its bundle or for a commit
readyPublished and reachable on its preview URL
liveCurrently serving the distribution's public URL
failedProcessing did not complete; the response explains why

Promotion is reversible ​

Because every deployment that reached ready is still published, moving between them is just a matter of which one the distribution points at. rollback copies an earlier deployment into a new one. Its files are copied as published, not rebuilt from source. Once the copy is ready, it is promoted: the CLI does both steps, and an agent promotes the restored deployment after checking it. The deployment you moved away from can be promoted again.

Settings travel with deployments too. Response headers and redirects belong to the distribution, but a change to them is recorded as a new deployment. Visitors see the new headers or redirect table when that deployment is promoted, and a rollback brings back the table the earlier deployment had.

What promotion does not control is caching. New content is published immediately, but copies already cached at the edge may serve the old version briefly. Invalidating the distribution clears them.

Promotes can wait for a set time ​

A promote does not have to happen when you ask for it. Scheduling one records the deployment and a time, and Edge promotes it within about a minute of that time. Nobody has to be online. The deployment is checked again when the time comes: if it is not ready, nothing goes live and the schedule is marked failed. See Schedule a launch and a takedown.

Taking a site down is not deleting it ​

A takedown answers visitors on the distribution's live addresses with 410 Gone or a temporary redirect, instead of serving the live deployment. It is a setting on the distribution, not a deployment, so:

  • nothing is deleted, and restoring brings the same live deployment back;
  • previews keep working;
  • promoting a new deployment does not lift it. You can stage the next campaign behind a takedown and restore when it is ready.

A takedown is different from suspension. Suspension is how the platform stops a distribution for abuse or a legal request. It answers 403 and is not something you set. If a distribution is suspended, it stays unreachable whether or not it is also taken down.

Why two interfaces behave identically ​

Edge is used both by people writing scripts and by agents calling MCP tools. These are not two implementations — each HTTP route and its MCP tool call the same handler, with the same permission check. An agent that publishes a site does exactly what a curl sequence would do.

This matters when you are supervising an agent: anything it can do, you can inspect, reproduce, or undo yourself through the API.

The one trap worth knowing ​

Creating a distribution returns a deployment id along with the distribution. That row exists for bookkeeping. It has no files and no queued work, and committing it does nothing useful.

The deployment you actually work with is the one returned when you explicitly create a deployment. If a commit seems to do nothing at all, this is almost always the reason.

See also ​