skip to content

Frontend Hosting

Pages deploys sites from Git with preview URLs, and Workers now serve static assets too, which Cloudflare recommends for new projects. Interviewers ask which to choose.

on this pageshow

explore

questions

17

In Cloudflare Pages with Git integration, what happens when you push to the production branch versus any other branch?

level: juniorimportance: must knowfreq 52%

answer

  1. one branch feeds production
  2. every other branch builds a preview
  3. hash URL versus branch alias
  4. custom domains follow production

basics

~20 s

A push to the production branch builds and replaces the live site on <project>.pages.dev and its custom domains. A push to any other branch builds a preview deployment with its own hash URL and a branch alias, leaving production untouched.

solid answer

~40 s

Pages watches the connected GitHub or GitLab repository and, on each push, runs the project's **build command** from its **root directory** and uploads the **build output directory**. The **production branch** you pick at setup (usually `main`) feeds the production environment: `<project>.pages.dev` plus every attached custom domain. Any other branch produces a **preview deployment** at `<hash>.<project>.pages.dev`, a URL fixed to that one build, and Pages also points a **branch alias** such as `fix-api.<project>.pages.dev` (for a `fix/api` branch) at the branch's latest build. Pull requests opened from branches of the same repository get the preview URL posted on them; pull requests from forks get no preview. Production and preview also read separate sets of environment variables, so a preview build need not see production values.

go deeper

for a junior

Recall that one branch is production and every other branch becomes a preview with its own pages.dev URL, and that custom domains only ever serve production.

for a middle

Explain the hash URL versus the branch alias, how the alias is derived from the branch name, and that the build command's exit code decides success.

for a senior

Show you can control build volume and exposure: branch deployment controls, build watch paths, skip prefixes, separate preview variables, and the fact that previews are public by default.

for a principal

Frame the pipeline as a policy: which branches may build, who sees previews, and whether new sites should start on Workers static assets instead of Pages.

## What the Git integration does on every push **Cloudflare Pages** is Cloudflare's hosting product for static sites built from a repository. When you connect a GitHub or GitLab repository to a Pages project, Cloudflare installs an app on that repository and reacts to pushes. For each push that is allowed to deploy, it: 1. clones the commit and changes into the **root directory** (the repository root unless you set another path, which a monorepo needs); 2. runs the **build command** you configured, such as the static site generator's own build script (leave it blank, or use `exit 0`, when there is nothing to build); 3. reads the command's **exit code**: non-zero marks the build failed, zero marks it successful even if errors were printed to standard error; 4. uploads the contents of the **build output directory** (for example `public` or `dist`) and publishes them as a new **deployment**. Builds time out after 20 minutes. On the Free plan an account runs one build at a time and 500 builds a month; paid plans raise both. ## The production branch Every project has exactly one **production branch**, chosen when you create it (typically `main`). A successful build of that branch becomes the production deployment and is served on: - `<project>.pages.dev`, the project's own subdomain; - every **custom domain** attached to the project. A new production deployment replaces the previous one on those hostnames. The older deployments are kept in the project's deployment list, which is what makes rollbacks possible. ## Preview deployments and their two URLs A build of any other branch is a **preview deployment**. It never touches production's hostnames. Each one is reachable two ways: | URL form | Points at | Changes when | |---|---|---| | `<hash>.<project>.pages.dev` | one specific deployment | never; it stays reachable for that build | | `<branch>.<project>.pages.dev` | the newest deployment of that branch | every new build of the branch | The branch alias is the branch name lowercased, with every non-alphanumeric character replaced by a hyphen, so `fix/api` becomes `fix-api.<project>.pages.dev`. Share the alias with reviewers who want "the latest of this branch", and the hash URL in a bug report that must point at one exact build. On GitHub and GitLab, Pages also posts the preview URL on a pull request and reports build and deployment status back to the repository. Two limits catch teams out: - commits and pull requests from **forked repositories** do not create previews; - previews are **public by default** and reachable by anyone with the URL until you enable the project's access policy. ## Controlling which pushes deploy Not every push has to build. Pages gives three controls: - **Branch deployment controls**: turn automatic production deployments on or off, and set previews to *All non-Production branches* (the default), *None*, or *Custom branches* with include and exclude patterns. Excludes are evaluated first, then includes, and a branch matching neither is skipped. With *Custom branches*, including `*` and excluding `deps/*` stops a dependency bot's branches from building. - **Build watch paths**: include and exclude file patterns, so a push that only changes `docs/*` in a monorepo can skip the site build. - **Commit message prefixes**: starting a commit message with `[CI Skip]`, `[Skip CI]` or `[CF-Pages-Skip]` (case-insensitive) skips that one deployment. ## Custom domains and branches Custom domains attach to **production**. To serve one preview branch on your own hostname, such as `staging.example.com` for a `staging` branch, add the domain to the project and then point its CNAME record at the branch alias, `staging.<project>.pages.dev`, instead of `<project>.pages.dev`. This works only with a **proxied** Cloudflare DNS record; through an external DNS provider or an unproxied record, the hostname is served the production branch instead. ## What the build can read Pages injects system variables into every build, which a build script can use to behave differently per branch: - `CF_PAGES` is `1` and `CI` is `true`; - `CF_PAGES_BRANCH` holds the branch name; - `CF_PAGES_COMMIT_SHA` holds the commit; - `CF_PAGES_URL` holds the URL of the deployment being built. Your own variables are set separately for the **production** and **preview** environments, so a preview build can use a test key while production uses the real one. ## Pages and Workers today Pages Git deploys keep working for existing projects, but Cloudflare's documentation now tells teams to **start new projects on Workers** with static assets, which covers most Pages use cases. Whether to move an existing site is covered with Workers static assets; this lesson is about how the Pages pipeline itself behaves.

  • Why does a Pages preview have both a hash URL and a branch alias?
    The hash URL, `<hash>.<project>.pages.dev`, belongs to one deployment and keeps serving that exact build. The branch alias, `<branch>.<project>.pages.dev`, is moved to each new build of the branch. Reviewers bookmark the alias to always see the latest work; a bug report links the hash URL so the reader sees the build where the bug appeared.
  • How do you stop a dependency bot's branches from each building a Pages preview?
    Use branch deployment controls: set preview deployments to *Custom branches*, include `*` and exclude the bot's prefix, for example `deps/*`. Pages evaluates excludes first, then includes, and skips a branch that matches neither. Setting previews to *None* turns automatic preview builds off entirely.
  • How does Pages decide that a Git build failed?
    By the build command's exit code. Any non-zero code fails the build and nothing is published; a zero exit code marks it successful and uploads the output directory, even if the log shows errors on standard error. A build that runs past 20 minutes times out.

A hash URL is a printed edition of a newspaper: that copy never changes. The branch alias is the paper's front page online, which always shows the newest edition of that branch.

  • Every push, on any branch, replaces the live site.
  • Custom domains show whichever branch was pushed most recently.
  • A branch alias URL stays pinned to one commit forever.
  • Pull requests from forks get preview deployments like any other branch.
  • A build that prints errors to standard error is marked failed.

As of 2026-10-10 the Pages docs tell teams to start new projects on Workers with static assets; Pages Git deploys still behave as described for existing projects.

open as a page

In Cloudflare Pages Functions, how do files under functions/ become routes, and how do [id] and [[path]] filenames capture URL segments?

level: juniorimportance: must knowfreq 35%

basics

~20 s

Each file under functions/ serves the URL path that mirrors its location, and index.js serves its folder. A [id].js file matches exactly one segment, read as a string from context.params.id; [[path]].js matches any depth and yields an array.

open as a page

In a Cloudflare Worker with static assets, which requests run the Worker's fetch handler and which are served straight from assets.directory?

level: juniorimportance: must knowfreq 45%

basics

~20 s

By default, a request whose path matches a file in assets.directory is served as that file without running the Worker. Only a miss invokes the fetch handler, which can answer itself or hand the request back with env.ASSETS.fetch().

open as a page

In Cloudflare Workers static assets, how does not_found_handling serve a single-page app, and how do its three values differ?

level: middleimportance: must knowfreq 45%

basics

~20 s

In Workers static assets, not_found_handling sets the reply when no file matches: single-page-application serves /index.html with 200, 404-page the nearest 404.html with 404, and none, the default, an empty 404. With a Worker script and no route patterns, non-navigation misses reach the script first.

open as a page

Why did adding functions/_middleware.js to a Cloudflare Pages site make every image and stylesheet request invoke Functions, and how does _routes.json fix it?

level: seniorimportance: must knowfreq 25%

basics

~20 s

Wrangler generates _routes.json from the functions/ tree, and a root _middleware.js makes it include /*, so every request invokes the Functions Worker. Scope the middleware to a folder such as functions/api/, or ship a custom _routes.json whose exclude list covers static paths.

open as a page

In Cloudflare Pages, how does a Direct Upload project deployed with wrangler pages deploy differ from a Git-integrated project?

level: middleimportance: should knowfreq 35%

basics

~20 s

A Direct Upload project receives files you already built, sent by wrangler pages deploy or a dashboard upload, while a Git project builds on Cloudflare after each push. The choice is fixed at creation: neither kind converts to the other.

open as a page

In Cloudflare Pages, what can you roll a production deployment back to, and what does a rollback leave unchanged?

level: middleimportance: should knowfreq 28%

basics

~20 s

A Pages rollback instantly makes an earlier, successfully built production deployment live again; preview deployments are not valid targets. It changes which deployment production serves, not the Git branch, so the bad commit is still at the branch tip.

open as a page

When a Cloudflare Pages project's build output contains a _worker.js file, what happens to its functions/ directory, and what must that Worker do?

level: middleimportance: should knowfreq 22%

basics

~20 s

A _worker.js in the build output switches the Pages project to advanced mode: the functions/ directory, its routing and its middleware are ignored. The file is a module Worker that receives every request and must call env.ASSETS.fetch() to serve static files.

open as a page

In Cloudflare Pages Functions, how do onRequest and method exports like onRequestPost decide which handler runs, and what does the context argument carry?

level: middleimportance: should knowfreq 28%

basics

~20 s

A route file exports onRequest for every method or onRequestGet, onRequestPost and the like for one; a method-specific export wins over onRequest. The handler gets a context with request, env, params, data, next(), waitUntil() and functionPath, and must return a Response.

open as a page

How do _middleware.js files in Cloudflare Pages Functions chain with context.next(), and how does an auth middleware pass the user to the handler?

level: middleimportance: should knowfreq 30%

basics

~20 s

A _middleware.js file runs before every Functions request under its folder, outer folders first. It exports onRequest, or an array run in order; each calls context.next() to continue or returns a Response to stop. Auth middleware stores the user on context.data for the handler.

open as a page

In Cloudflare Workers static assets, when do you need run_worker_first, and how do its true and route-pattern forms differ?

level: middleimportance: should knowfreq 35%

basics

~20 s

Use run_worker_first when code must see a request before a matching file is served, such as an auth check. true runs the Worker for every request; an array of route patterns, with ! exclusions, runs it only for matching paths.

open as a page

A Cloudflare Pages project builds a preview for every pull request of an unreleased site; how do you keep those previews private and unindexed?

level: seniorimportance: should knowfreq 36%

basics

~20 s

Enable the Pages project's access policy, which puts Cloudflare Access in front of every *.<project>.pages.dev preview, and rely on the X-Robots-Tag: noindex header Pages adds there. Neither covers <project>.pages.dev or custom domains, so handle those separately.

open as a page

Why do rules near the end of a Cloudflare Pages _redirects file do nothing when it opens with a /blog/* splat rule followed by 300 exact-path redirects?

level: seniorimportance: should knowfreq 24%

basics

~20 s

Pages allows 2,000 static and 100 dynamic _redirects rules, and once the first splat or placeholder rule appears, every later line counts as dynamic. The splat plus the first 99 exact paths use the dynamic budget; the remaining lines are skipped.

open as a page

Why might context.env.MESSAGES still be undefined in a Cloudflare Pages Function after a KV binding named MESSAGES was added in the dashboard?

level: seniorimportance: should knowfreq 25%

basics

~20 s

Pages attaches bindings when a deployment is created, so the project needs a redeploy after a dashboard change. Preview and production keep separate bindings, a Wrangler file with pages_build_output_dir replaces dashboard settings, and wrangler pages dev reads only the Wrangler file or flags.

open as a page

After moving an SPA from Pages to a Cloudflare Worker with single-page-application fallback, the browser's OAuth redirect to /auth/callback returns index.html and never reaches the Worker; why, and how do you fix it?

level: seniorimportance: should knowfreq 25%

basics

~20 s

The provider's redirect is a browser navigation carrying Sec-Fetch-Mode: navigate, and for compatibility dates from 2025-04-01 a navigation that misses is answered with the SPA fallback without invoking the Worker. List the route in run_worker_first, or finish the exchange from client-side code.

open as a page

For a team running an SPA and its API on Cloudflare Pages, how would you decide whether and when to move it to a Worker with static assets?

level: principalimportance: should knowfreq 30%

basics

~20 s

Cloudflare now points new projects to Workers with static assets, so new sites start there. An existing Pages app moves when it needs a Workers-only feature or a major rework, unless it relies on a domain outside Cloudflare's nameservers or Pages-only branch controls.

open as a page

When moving a Pages build output to Cloudflare Workers static assets, what happens to its _headers, _redirects and _worker.js files, and what does .assetsignore do?

level: middleimportance: nice to knowfreq 25%

basics

~20 s

Workers static assets read _headers and _redirects from the assets directory as rules, not files, applying them only to asset responses. A Pages _worker.js would become a public file, so wrangler deploy refuses it while no .assetsignore exists: move it out or list it there.

open as a page