Rollback Strategy When a Deploy Breaks the Site

The moment you need a rollback is the worst moment to learn what your platform’s rollback does not cover. So the useful exercise is to run one on purpose, while nothing is on fire, and find out.

I did that. Three findings were not what I expected: the rollback is genuinely instant, it is reversible in the forward direction, and the workflow I actually use — wrangler direct upload — has no rollback command at all.

Rollback is not undo

A rollback moves your production alias back to an earlier deployment. That is all it does, and the distinction matters because we tend to think of it as “undo the last thing I did.”

It does not undo the last thing you did. It points traffic at a different set of already-built files. Anything your last deploy changed outside the files — an environment variable, a DNS record, a redirect rule in the zone, a third-party webhook you registered — is untouched and still in its new state.

Hold that thought; it is the source of every surprise in this article.

What Cloudflare Pages actually allows

The API documentation for the rollback endpoint states the constraint precisely: “Rollback the production deployment to a previous deployment. You can only rollback to succesful builds on production.”

Three conditions are packed into that sentence. The target must be a build, it must have been a production deployment, and it must have succeeded. A failed build is not a rollback target. And the rollback page says the next part outright: “Note that preview deployments are not valid rollback targets.”

So the set of things you can roll back to is narrower than the set of things you can see. If your last good state only ever existed as a preview deployment, you cannot roll back to it — you have to deploy it to production first.

Two things in Cloudflare’s favour:

Rollback is reversible. The docs confirm you can roll back to deployments newer than your current version. A rollback is not a one-way door, so the pressure of the decision is lower than it feels.

It is genuinely immediate. In the dashboard, Deployments → All deployments → the three-dot menu → “Rollback to this deployment,” and “your project’s production deployment will change instantly.”

There is also a separate retry endpoint — “Retry a previous deployment” — which is a different operation. Retry re-runs a build. Rollback changes which build is live. If a deploy failed because of a transient build error, you want retry.

The wrangler gap

Here is the finding that changed my own procedure. The wrangler pages deployment subcommands are list, tail, and delete. There is no rollback, and no promote.

For a direct-upload project, rollback is dashboard-or-raw-API only:

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/pages/projects/your-project/deployments/$DEPLOYMENT_ID/rollback" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

That means the fast path in an incident is a browser session, not a terminal — and it means if you have no dashboard access, your rollback plan does not exist. Anyone who has been on the wrong end of an expired session at 2am should treat that as a real risk, not a theoretical one.

What the rollback leaves behind

This is the part the docs are quiet about, and it is the part that actually bites.

When you roll back, you get the assets from the earlier build. What you do not get is the configuration that build assumed. Concretely:

• Environment variables are whatever you have set now, not what they were then.
• Bindings and secrets are current, not historical.
• Any request-header or redirect rules you changed outside the deployment are still changed.
• Cloudflare’s docs describe rollback targets as “builds,” but never say whether a rolled-back deployment re-applies the current configuration or its original one.

Vercel, to its credit, documents the equivalent hazard explicitly — warning that after a rollback, environment variable changes are ignored and configuration “may become stale.” Cloudflare documents nothing comparable.

The practical consequence: a rollback can put old code in front of a new environment. If the thing that broke the site was a code change, rollback fixes it. If the thing that broke the site was a config change, rollback does not, and you now have a mismatch that is harder to reason about than the original problem.

How far back can you go?

Netlify documents the answer for its own platform: deployments are automatically deleted after 30 days on free plans, 90 on paid, which bounds your rollback window whether or not you thought about it.

For Cloudflare Pages, no retention window for rollback targets appears in the documentation. Absence of a stated limit is not a promise of a permanent one, and I would not build a recovery plan on the assumption that last quarter’s deployment is still addressable.

The safe assumption for any platform: your rollback window is days, not months. If you need to return to a state from long ago, that is a redeploy from source control, not a rollback.

The other two platforms, briefly

	Cloudflare Pages	Netlify	Vercel
Term used	“Rollback to this deployment”	“Publish Deploy”	“Instant Rollback”
Rebuild triggered?	No	No — “publishes a previous atomic deploy”	No
Eligibility rule	Successful production builds only	Any retained deploy	Previously aliased to production
Free-tier limit	Not documented	30-day retention	Immediately previous deployment only

Netlify calls it “Publish Deploy,” not rollback, which is a real usability problem when you are searching for help during an incident.

Vercel’s eligibility rule is the subtlest: rollback targets are chosen by alias history, not by time, and “most preview deployments are not eligible.” On the Hobby plan you can roll back to the immediately previous deployment and no further.

The Vercel behaviour worth knowing about even if you do not use Vercel: “After a rollback, Vercel turns off auto-assignment of production domains.” Your next push will not redeploy until you undo the rollback. Silent, and exactly the kind of thing that turns one incident into two.

When rollback is the wrong move

Rollback is the right call when a deploy broke something and you have a known-good target. It is the wrong call when:

• The break came from configuration, not code. Rollback will not touch it, and you will have added a version mismatch on top of the original problem.
• The change is a security fix. Rolling back re-opens the hole.
• You are rolling back to hide a symptom. If the last three deploys were fine and the site is still broken, the deploys are not the problem.

Write it down before you need it

Four lines, prepared in advance, are worth more than any amount of rollback capability:

1. The exact dashboard path to the rollback control, and a confirmed working login.
2. An API token with Pages write permission, stored somewhere you can reach without your laptop.
3. wrangler pages deployment list output saved somewhere, so you can identify the target deployment ID when the dashboard is slow.
4. A one-line answer to “was this a code change or a config change?” — because that single question decides whether rollback is a fix or a detour.

Then actually run a rollback once, on a quiet afternoon, and roll forward again. The feature works. The gap is never in the feature.