In Cloudflare Pages with Git integration, what happens when you push to the production branch versus any other branch?
answer
- one branch feeds production
- every other branch builds a preview
- hash URL versus branch alias
- custom domains follow production
basics
~20 sA 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 sPages 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
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.
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.
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.
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.