Releases
How to roll back a website deploy
How to roll back a website deploy: record the live deploy ID first, test every page after the release, and restore the old version before you debug.
IO Creative3 min read
To roll back a website deploy, publish the previous deploy again from your host. It takes seconds, but only if you wrote down which deploy was live before you shipped. Record that ID first, check the new version right after release, and restore the old one at the first failure.
Write down the live deploy before you ship
A rollback needs a target. Most hosts keep every earlier deploy as its own saved copy of the site, and each one has an ID. Before you publish anything, copy the ID of the deploy that is live right now and put it where the next person can find it: the pull request, the ticket or the release note.
Without it, you find the right version while the site is broken and a customer is looking at the error. With it, the fix is one action. Netlify's documentation describes the same step: open a successful earlier deploy and publish it as the live version of the site (Manage deploys).
Test the live site, not only the preview
A preview passing does not prove production works. The live domain has its own settings, its own cache and its own environment variables. Right after the release, check the real address:
- Open the home page and the page you changed, and confirm the change is visible.
- Request every URL in the sitemap and confirm each answers with the right status and title.
- Load the images the home page uses. Pages can return 200 while every photo fails, because images are often served by a separate route.
- Compare the response headers with the previous deploy, in particular the cache headers on static files.
Run the same list every time. A fixed list is quick to repeat and catches what a quick look at the home page misses.
Roll back a website deploy first, debug second
When one check fails, restore the recorded deploy before you look for the cause. The rule is simple because the cost is lopsided: a few minutes on the old version costs almost nothing, and an hour of a broken site costs sales, trust and search rankings.
After the restore, run the same checklist again. A rollback is only done when the old version passes the checks it passed before. Then debug the failed release on a branch, with the failure in hand, without anyone waiting.
Some hosts also let you lock publishing to one deploy, so a later push cannot replace it while you investigate (Netlify's rollback walkthrough). Use that when the cause is not yet known.
What a rollback does not undo
A rollback restores the site's files and build. It does not restore everything the site depends on:
- Content in a CMS or database. If the new release came with a content change or a schema change, the old code may not read the new data. Note the old value before you change it.
- Settings in your host's dashboard. Environment variables, redirects set in the dashboard and domain settings are not part of a deploy. Record the previous value of any setting you change, on the same ticket as the deploy ID.
- DNS. Domain records sit outside the deploy, so a bad DNS change needs its own undo.
- Anything customers already did. Orders and form submissions made on the broken version stay made.
So a good release note lists three things: the deploy ID to go back to, the settings that changed with their old values, and the checks that passed.
Make the release small
The easiest rollback is the one you rarely need. Ship one change at a time, so a failure points to one cause. Build the site where you can read the full log, and look at a preview of that exact build before it goes live. If you run a site that earns money, keep a person or a routine responsible for the live check after every release.
That is part of how we look after client sites: a recorded rollback ID, a live check of every page, and a restore at the first failure. If you want that for your site, see hosting and care.
