Understanding Netlify Atomic Deploys: Snapshot, Rollback, and Caching

What you get: an immutable snapshot that rolls back instantly

Every time you push to Netlify, the platform builds your site and publishes the entire output as one immutable snapshot. Visitors either see the complete previous version or the complete new version – never a mix of half‑updated files. Because the snapshot is immutable, rolling back is just a matter of telling Netlify to point the production alias at any earlier snapshot; no rebuild is required and the change takes effect within seconds.

Worked example: configuring long‑term caching for fingerprinted assets

To take full advantage of atomic deploys you should cache hashed assets forever while keeping HTML always revalidated. The following netlify.toml shows a typical split for a Vite or Webpack build that emits fingerprinted filenames like main.abc123.js.

# netlify.toml
[build]
  command = "npm run build"
  publish = "dist"

[[headers]]
  # Apply to all HTML – always revalidate
  for = "/*.html"
  [headers.values]
    cache-control = "public, max-age=0, must-revalidate"

[[headers]]
  # Fingerprinted assets – cache forever, treat as immutable
  for = "/assets/*"
  [headers.values]
    cache-control = "public, max-age=31536000, immutable"

Place this file at the root of your repository. When Netlify runs the build, the dist folder is uploaded as a snapshot. The HTML header forces browsers to check for a new version on every request, while assets with content hashes can be safely cached for a year because any change to the file produces a new URL.

How to verify the headers

1. Deploy the site (e.g., netlify deploy --prod --dir .).
2. Once the deploy is live, fetch an HTML page and an asset:

# Replace with your live URL
curl -I https://example.netlify.app/index.html
curl -I https://example.netlify.app/assets/main.abc123.js

Check that the first response includes cache-control: public, max-age=0, must-revalidate and the second includes cache-control: public, max-age=31536000, immutable. If the values differ, review your build tool’s output to ensure filenames are actually fingerprinted.
Rolling back to a previous snapshot
Because each deploy is immutable, you can restore a prior version instantly:

  
Open the Netlify dashboard, go to Site overview → Deploys.
  
Locate the deploy you want to restore, click the three‑dot menu, and choose Publish deploy.
  
Netlify updates the production alias to point at that snapshot; the live site changes within seconds, with no rebuild.

If you prefer the command line, you can achieve the same effect via the Site API. The following curl call re‑points the production branch to a specific deploy ID (you need a personal access token with sites scope):
curl -X PATCH \
  -H "Authorization: Bearer $NETLIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch_deploy":""}' \
  https://api.netlify.com/api/v1/sites/

Replace $NETLIFY_TOKEN, , and  with your values. The request updates the site’s branch target; the change is immediate.
Limits and common mistakes
Limits

  
Atomic deploys and instant rollback work for the site’s files, functions, and redirects, but they do not revert external state such as databases, form submissions, or third‑party APIs.
  
Build minutes, function invocations, and bandwidth are still governed by your current Netlify plan; check the billing page for exact quotas.
  
The netlify.toml schema is versioned; a typo can cause headers to be ignored silently. Always validate the file with netlify toml:validate (Netlify CLI) before committing.

Common mistakes

  
Long‑cache headers on non‑fingerprinted files – If your build does not emit hashed names (e.g., you serve main.js unchanged), browsers will keep the old version forever after a deploy, leaving users with stale code.
  
Assuming environment variable changes apply without a new deploy – Netlify injects env vars at build time; altering a variable in the dashboard does not affect the live site until you trigger a new build.
  
Overlooking that a failed build leaves the previous deploy live – This is usually desirable (downtime is avoided), but it can hide a broken build if you only check the deploy log and not the live site.
  
Mixing cache‑control directives – Using both immutable and a short max-age on the same path creates contradictory instructions; browsers may ignore the immutable flag.

Practical verification checklist

  
Deploy two successive versions with visible changes (e.g., edit a line of text).
  
Confirm the live site shows the second version.
  
Use the UI or API to roll back to the first deploy ID.
  
Reload the page and verify the original text is back.
  
Run the curl -I checks above to ensure headers match your netlify.toml.

If the rollback is instantaneous and the headers are correct, you have successfully used Netlify’s atomic deploy model.