skip to content

Pages Git Deploys

Pages builds each Git push, serves production from one branch and gives every other branch a preview URL. Interviewers ask how previews are protected and how _redirects apply.

on this pageshow

explore

questions

5

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, 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

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