Patch, promote, and roll back
This page assumes you already have a live distribution. If not, start with Publish your first site.
Throughout, the distribution is d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38. Each step shows both ways of working: describing the task to an agent, using the CLI, or calling the API yourself.
Where you can do this
Promoting and rolling back are not available in the web console. The console shows you distributions, deployments, domains, analytics and request logs, but it does not perform these actions. Use an agent, the CLI, or the API.
The console is still the right place to check the result — the Deployments page at https://app.edge.deca-dev.com/edge/{workspaceId}/deployments shows which deployment is live.
Ship a new version
If the whole site is rebuilt
When your build regenerates everything — a static site generator, a bundler — upload a fresh archive.
Publish a new deployment of ./dist to the acme-marketing distribution,
then give me the preview URL. Do not promote it yet.edge deploy ./dist --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38# open a deployment, upload, commit, poll, then promote
curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/deployments \
-H "Authorization: Bearer $EDGE_TOKEN"
COPYFILE_DISABLE=1 tar -czf ../bundle.tar.gz -C ./dist .
curl -s -X PUT --upload-file ../bundle.tar.gz "$UPLOAD_URL"
curl -s -X POST https://api.edge.deca-dev.com/v1/deployments/$DEPLOYMENT_ID/commit \
-H "Authorization: Bearer $EDGE_TOKEN"Then check the preview and promote, as in step 7 of the tutorial.
Telling the agent not to promote is worth doing explicitly. Promotion is the step that changes what the public sees, and it should follow you looking at the preview rather than happen as part of one instruction.
If you are changing a few files
When you only want to patch some text files, branch from the deployment that is already live instead of re-uploading everything.
Branch a new deployment from the live one on acme-marketing, change the
heading on about.html to "About our team", commit it and show me the preview.edge deployments create --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --from 01M2QB6JJJS99B7B09VZJ8RST2
# then write onto the new pending deployment id:
edge api PUT /v1/deployments/01M2QF4XK7T0N8MB2VD31HGA9C/content --input - <<'EOF'
{ "objects": [{ "path": "about.html", "content": "<!doctype html>…" }] }
EOF# branch from the live deployment
curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/deployments \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "from_deployment": "01M2QB6JJJS99B7B09VZJ8RST2" }'
# write only the changed files onto the new pending deployment
curl -s -X PUT \
https://api.edge.deca-dev.com/v1/deployments/01M2QF4XK7T0N8MB2VD31HGA9C/content \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "objects": [{ "path": "about.html", "content": "<!doctype html>…" }] }'Do not also upload a tarball on a branched deployment. Commit, check the preview, promote. The worker copies everything from the source deployment and applies your writes on top.
This path suits agents particularly well: an agent can read the published file, edit it, and write it back without ever having your source tree.
To see what is currently published before patching it, read the live deployment's files — edge_content_list and edge_content_get, or GET /v1/deployments/{id}/content. Those read published files, not the contents of the original archive.
Inline writes are capped at 100,000 bytes per file and 2 MB across one call. A file over that cap, or a binary, goes in a complete bundle on a deployment opened without from_deployment. See Upload content and Limits.
Roll back
If a promoted deployment is wrong, put the previous one back.
Roll back acme-marketing to the previous deployment.edge deployments rollback --distribution d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/rollback \
-H "Authorization: Bearer $EDGE_TOKEN"Rolling back copies the earlier deployment's published files into a new deployment. Nothing is rebuilt from source and nothing is lost: the deployment you rolled away from still exists and can be promoted again. The CLI waits for the copy to be ready and promotes it. An agent runs edge_deployment_rollback, waits for the restored deployment to be ready, then runs edge_deployment_promote on it. The API works the same way: call POST /v1/deployments/{id}/promote on the deployment_id the rollback returns.
Compare two deployments first
Show me what changed between the live deployment and the one I just built.edge deployments diff 01M2QB6JJJS99B7B09VZJ8RST2 01M2QF4XK7T0N8MB2VD31HGA9Ccurl -s "https://api.edge.deca-dev.com/v1/deployments/01M2QB6JJJS99B7B09VZJ8RST2/diff/01M2QF4XK7T0N8MB2VD31HGA9C" \
-H "Authorization: Bearer $EDGE_TOKEN"The agent runs edge_deployment_diff.
Clear the cache
Promote and rollback already request a full /* invalidation for the new live deployment. Use a manual invalidation when you need to retry a purge for paths on the live content deployment.
Invalidate the cache for acme-marketing.edge distributions invalidate d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38 --path '/*'curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/invalidate \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "paths": ["/*"] }'The agent runs edge_distribution_invalidate. Paths are viewer paths beginning with /; Edge translates them onto the current live deployment prefix. Invalidation changes neither files nor config.
Promote later
To make a deployment go live at a set time instead of now, schedule the promote. You can also take a site down when a campaign ends. See Schedule a launch and a takedown.
Next
- Schedule a launch and a takedown
- Deployment lifecycle — what
pending,readyand live mean - Attach a custom domain
- Limits