How Netlify Cloud deploys and serves a site
Trace a Netlify deploy from source trigger and build output to immutable addressing, global delivery, edge logic, atomic publish, and rollback.
The whole story in 6 lines
See how Netlify builds immutable deploys, serves them from edge locations, runs dynamic logic, and promotes or rolls back atomically.
- Git, hooks, and manual uploads converge on the same deploy queue after Netlify resolves site and branch context.
- One build assembles static assets, functions, edge handlers, and manifest metadata into an internally consistent deploy.
- Unchanged files can be reused, but every successful deployment still receives its own immutable deploy ID and URL space.
- An edge point of presence fetches a missing immutable file once, then serves nearby requests from its warmed cache.
- Edge code handles fast request steering, while functions handle heavier compute and data access.
- Production is an alias to one immutable deploy ID, so promotion and rollback update a pointer instead of rebuilding.
Setup
A production update seems fine in preview, but one bad release must be reversed before visitors are affected. Netlify solves that problem by keeping complete site versions separate. First, let us learn four terms for the journey.
A deploy is one complete snapshot of a site at a particular moment. New code creates a new deploy, while earlier deploys remain available for inspection or recovery.
A build turns source code into browser files and runtime bundles. Think of it as a workshop that packages one consistent candidate before anything becomes public.
The edge is a nearby Netlify location that receives a visitor's request. It can serve cached files or run lightweight routing before heavier function work begins.
An alias is a stable public name that points to one immutable deploy. Because the name can move while deploys stay frozen, promotion and rollback become clean pointer changes.
Our roadmap follows the trigger, build, immutable deploy, global delivery, dynamic runtime, and final alias swap. Let us begin with the concrete event that creates a deploy job.
Deploy Trigger Intake
Now that we know the vocabulary, let us see where every deploy begins. A trigger enters Netlify when you push code, fire a deploy hook, or move files into the dashboard.
Netlify maps that trigger onto a specific site and branch context. Git pushes, deploy hooks, and manual drops all converge into the same deploy queue once Netlify has identified the site and branch context.
Once the context is resolved, Netlify normalizes the trigger into a single deploy job and places it in a queue.
A build image claims the next job from the queue and pulls the exact source snapshot. This means Netlify locks the commit so nothing can change under the build while it runs.
The build environment is now ready to produce deploy artifacts. Every trigger, whether it came from Git, a webhook, or a manual upload, follows the same path from this point forward. Next we will see what the build actually produces.
Build Output Assembly
Now that the trigger has claimed a build slot, the build image boots up. It restores cached dependencies and loads your environment variables so the compile step starts fast. This detail matters because it determines the state handed to the next part of the system.
The build command compiles your source files into static assets like HTML, CSS, and JavaScript for this candidate deploy.
The stage has reached the decision that determines its next state. What must finish before a new Netlify deploy becomes live?
If your site uses edge handlers, they are compiled in this step. Static files, serverless functions, edge handlers, and manifest metadata are all produced together so the deploy can stay internally consistent.
Finally, one deploy manifest records every artifact the build produced: static files, functions, edge code, headers, and redirects. This manifest is the single source of truth that the next stage will freeze into an immutable deploy.
Immutable Deploy Addressing
Now that the build has produced its manifest, Netlify fingerprints every file in the bundle. Each file gets a content hash so the platform knows exactly what changed since the last deploy.
Netlify uploads only the files that actually changed and reuses duplicates from earlier deploys. Netlify can reuse unchanged files across deploys, but every successful deploy still gets its own immutable deploy ID and URL space.
A new deploy ID freezes the exact manifest. From this moment on, that deploy is immutable. Nobody can edit its files in place, just like a published book edition that can never be revised.
Every deploy gets a stable permalink. Netlify can reuse unchanged files across deploys, but every successful deploy still gets its own immutable deploy ID and URL space.
Older deploys stay available alongside the new one. Because every deploy is immutable, you can promote or inspect any of them at any time. Next we will see how these frozen files reach visitors around the world.
Global Static Delivery
Now that we have an immutable deploy with stable addresses, let us follow a real request. A browser asks for one hashed file from the published deploy.
The request lands at the nearest Netlify edge POP, which is a server close to the visitor. The POP checks its local cache to see if it already has that file.
On a cache miss, the POP reaches back to the immutable deploy store and fetches the exact file by its content hash. Because the deploy is frozen, this file can never change unexpectedly.
The file streams back to the POP, which caches it locally and sends it to the visitor at the same time. You can see the cache meter fill up as the edge warms.
The next visitor nearby gets that same file directly from the POP with no round trip to the deploy store. This is how static delivery stays fast everywhere. Next we will look at what happens when a request needs more than a static file.
Edge Logic + Functions
Now that we understand how static files reach the edge, let us see what happens when a request needs dynamic logic. A route that matches an edge handler or serverless function enters the runtime pipeline instead of the static cache.
Edge code runs at the nearest POP, just like the static cache from the previous stage. It can inspect cookies, headers, and visitor geography to rewrite or redirect the request before heavier compute starts.
When the request needs heavier compute, Netlify invokes a serverless function. This function handles tasks like rendering a full page, checking authentication, or processing an API call.
The function can call databases or third party APIs to gather the data it needs.
The finished response flows back through the edge, which attaches final headers and a cache policy. Edge logic handles the fast, lightweight work while functions handle the heavy lifting. Next we will see how Netlify safely promotes a deploy to production.
Atomic Promotion + Rollback
★ If you remember one thing · Promotion changes one production alias to the new immutable deploy while the older deploy remains preserved.
After request delivery, the remaining question is how a new deploy becomes live. A candidate deploy can remain in preview during validation without disturbing the current production site. That isolation keeps validation separate from production traffic. Because both snapshots are immutable, preview testing cannot alter either release.
After validation, both deploys remain intact. What changes when Netlify promotes or rolls back a deploy?
The production alias now names deploy-43, while deploy-42 remains complete beside it. Every edge POP resolves traffic through that single alias, so publication never exposes a half-updated file set.
Switch the Mode control through Preview, Promote, and Rollback. Watch the alias outcome change while both deploy bundles remain fixed.
The older deploy remains available, so a rollback only repoints the production alias to deploy-42. No rebuild or reupload is required because both bundles were preserved. Now let us step back and connect the full pipeline.
Recap
Remember the deploy trigger from Stage 1. That is where every cycle begins. A git push, a deploy hook, or a manual upload kicks off the whole pipeline, just like dropping a letter into a mailbox starts the postal system.
The build step (Stage 2) takes your source code and compiles it into static files, functions, and edge handlers. Think of it as the kitchen in a restaurant: raw ingredients go in, finished dishes come out.
Once built, the output becomes an immutable deploy (Stage 3). It gets a permanent ID and a permanent URL. Like a published book edition, it can never be altered after the fact.
Stage 4 followed one immutable file into global delivery. The first request at a POP fetches that exact file and warms its cache, so nearby visitors can reuse the local copy.
When a request needs more than a static file, edge functions and serverless functions step in (Stage 5). Edge code handles lightweight personalization close to the visitor, while heavier compute runs in a serverless function.
Finally, the atomic promotion step (Stage 6) flips the live site from one deploy to another in a single pointer swap. If something goes wrong, rollback does the same thing in reverse, with no rebuild needed.
And the loop closes. The next git push starts a brand new cycle through all six stages. Every deploy is immutable, every release is atomic, and the edge serves traffic globally. That is how Netlify Cloud works.
The whole story in 6 lines
See how Netlify builds immutable deploys, serves them from edge locations, runs dynamic logic, and promotes or rolls back atomically.
- Git, hooks, and manual uploads converge on the same deploy queue after Netlify resolves site and branch context.
- One build assembles static assets, functions, edge handlers, and manifest metadata into an internally consistent deploy.
- Unchanged files can be reused, but every successful deployment still receives its own immutable deploy ID and URL space.
- An edge point of presence fetches a missing immutable file once, then serves nearby requests from its warmed cache.
- Edge code handles fast request steering, while functions handle heavier compute and data access.
- Production is an alias to one immutable deploy ID, so promotion and rollback update a pointer instead of rebuilding.