documentation menu

How deploys work

Hash locally, upload only what is missing, flip one pointer — why deploys are atomic and rollback is instant.

read as markdown

Pages uses a “git-push” style deploy: the work of figuring out what changed happens on your machine, so the network only ever carries new bytes.

  1. Hash locally. The CLI walks your directory, computes the SHA-256 of each file, and builds a manifest mapping every path to its content hash.
  2. Ask what’s missing. It sends the manifest up; the service replies with just the hashes it hasn’t seen before.
  3. Upload only those. The CLI uploads only the missing blobs, addressed by hash. Unchanged files — frameworks, libraries, images shared with earlier deploys — are never re-sent.
  4. Publish atomically. Once every blob is present, the manifest is stored as the new release. Going live is a separate step: the site’s active-version pointer flips to that release in one operation. That flip is the whole of both deploying and rolling back, which is why a staged release costs nothing to keep and a rollback is instant.

Every file is stored once by its content and served with long-lived, immutable caching, so repeat visits and files shared across sites load instantly. Nothing is ever mutated in place, which is what makes deploys atomic and rollbacks free.

Consequences worth knowing

The version id is a content hash. It is computed over the whole manifest — every path and hash, plus the release’s settings. Two releases with the same id are the same release. Re-deploying an unchanged folder uploads nothing.

A staged release is fully uploaded. “Staged” is not “partially deployed” — every byte is already in place and the only thing missing is the pointer. That is why promoting a preview cannot fail halfway, and why the preview a reviewer approved is byte-identical to what goes live.

Deleting a release does not delete files. Blobs are shared across releases and across sites, so removing a release removes a manifest. Storage is charged on distinct content, not on the number of releases pointing at it.

Caching is content-addressed, so there is no cache to purge. A changed file is a different hash at a different URL; an unchanged one keeps its long-lived cache entry. There is no “clear cache” button because there is nothing a stale cache could serve.