skip to content

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%

answer

  1. who runs the build
  2. branch decides production or preview
  3. branch read from the Git checkout
  4. a one-way choice at creation

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.

solid answer

~40 s

With **Direct Upload** you build wherever you like, often your own CI, and run `wrangler pages deploy dist --project-name site`. Pages makes it a **production** deployment when the branch sent equals the project's production branch, and a **preview** with a branch alias otherwise. Pass `--branch` explicitly; without it, inside a Git checkout, Wrangler reads the current branch and commit itself. CI authenticates with `CLOUDFLARE_API_TOKEN` (an account token with Cloudflare Pages Edit) and `CLOUDFLARE_ACCOUNT_ID`. The project type is permanent: a Direct Upload project cannot add Git integration later, and a Git project cannot become Direct Upload, though it can switch off automatic deployments and be deployed with `wrangler pages deploy` instead. Direct Upload is also the route for a Git provider Pages does not integrate with.

code

bash · 4 lines
bash
export CLOUDFLARE_ACCOUNT_ID="$CF_ACCOUNT_ID"
export CLOUDFLARE_API_TOKEN="$CF_PAGES_TOKEN"
npm run build
npx wrangler pages deploy dist --project-name marketing-site --branch "$BRANCH_NAME" --commit-hash "$COMMIT_SHA"

go deeper

for a junior

Recall that Direct Upload means you build and upload the files, while Git integration has Cloudflare build after each push, and that the choice cannot be reversed.

for a middle

Explain how wrangler pages deploy decides production versus preview from the branch, how it infers the branch from Git, and which two variables a CI job needs.

for a senior

Show the failure modes: a detached-HEAD checkout deploying as a preview, an over-scoped token, and a Git project that must be paused rather than converted.

for a principal

Weigh owning a build pipeline and its token against Cloudflare's managed builds, knowing the project type is fixed at creation.

## Two ways to feed a Pages project A **Cloudflare Pages** project gets its files in one of two ways, chosen when the project is created: - **Git integration**: Pages connects to a GitHub or GitLab repository, runs your build command on Cloudflare's build image after each push, and publishes the output directory. - **Direct Upload**: you build the site yourself and hand Pages the finished files, either with Wrangler (Cloudflare's CLI) or by dragging a folder or zip file into the dashboard. Direct Upload fits teams that already have a CI system, need a build step Pages' build image does not offer, or keep their code with a Git provider Pages does not connect to (anything other than GitHub or GitLab, including self-hosted instances of those two). ## Deploying with Wrangler The first deploy creates the project, or you create it explicitly: ```bash npx wrangler pages project create site --production-branch main npx wrangler pages deploy dist --project-name site --branch main npx wrangler pages deploy dist --project-name site --branch feature-x ``` `wrangler pages deploy` uploads one directory of static files (Wrangler does not accept a zip) plus, if present, a `functions` folder. The files `_redirects`, `_headers` and `_routes.json` are read as configuration and are not served as assets. ## How a deploy becomes production or preview Every deployment is attached to a branch name, and Pages compares it with the project's **production branch**: 1. If `--branch` is passed, that name is used. 2. If it is not, and Wrangler runs inside a Git working tree, it reads the current branch with `git rev-parse --abbrev-ref HEAD`, plus the commit hash and message. 3. Pages makes the deployment **production** when that branch equals the production branch, and a **preview** otherwise, with a branch alias at `<branch>.<project>.pages.dev`. Two consequences matter in practice: - A CI job that checks out a commit in **detached HEAD** has a current branch name of literally `HEAD`, so a deploy without `--branch` lands as a preview, not production. Always pass `--branch` in CI. - A developer running the same command from a laptop checkout of `main` deploys to production. Restrict who holds a token that can deploy. Pages also refuses `--env` on this command and tells you to use `--branch` to choose production or preview. ## What Wrangler records with each deploy Each deployment carries Git metadata that the dashboard shows beside it: - `--commit-hash` and `--commit-message` set the commit; inside a Git tree Wrangler fills them from `HEAD` when you leave them out; - `--commit-dirty` marks a deploy made from a working tree with uncommitted changes; when it is not set and the tree is dirty, Wrangler prints a warning telling you to pass `--commit-dirty=true`; - the project name and production branch you gave on the first run are cached under `node_modules/.cache/wrangler`, so later runs on that machine can omit them. CI runners usually start clean, so pass `--project-name` every time. ## Authenticating from CI Wrangler in CI does not log in interactively. It reads two environment variables: | Variable | Holds | |---|---| | `CLOUDFLARE_API_TOKEN` | an API token with the *Account / Cloudflare Pages / Edit* permission | | `CLOUDFLARE_ACCOUNT_ID` | the account that owns the project | Store both as the CI system's secrets. A narrowly scoped token that can only edit Pages limits the damage if a pipeline leaks it. ## The choice is one-way The Pages documentation is explicit in both directions: - A **Direct Upload** project cannot switch to Git integration later. Moving to automatic Git builds means creating a new project. - A **Git-integrated** project cannot switch to Direct Upload. It can, however, turn off automatic production deployments and set previews to *None* in branch deployment controls, then be deployed with `wrangler pages deploy` from your own pipeline. A Direct Upload project also has no branch-control screen; changing its production branch is done through the Pages project API. ## Limits to know | Method | Files per deployment | Largest file | |---|---|---| | Wrangler | 20,000 on the Free plan | 25 MiB | | Dashboard drag and drop | 1,000 | 25 MiB | A dashboard drag-and-drop deployment also cannot compile a `functions` folder; Wrangler can. Files larger than 25 MiB belong in object storage rather than in the site's assets. ## Picking one Git integration gives build logs, pull request previews and status checks with no pipeline to maintain. Direct Upload gives you control over the build environment and lets one CI pipeline deploy to several targets, at the price of owning that pipeline and its token. Because neither converts to the other, decide before the project is created.

  • Your CI runs `wrangler pages deploy dist --project-name site` without `--branch` and the release never reaches production. Why?
    Without `--branch`, Wrangler takes the branch from `git rev-parse --abbrev-ref HEAD`. Many CI systems check out a commit in detached HEAD, where that command prints `HEAD`. That name does not match the production branch, so Pages creates a preview. Pass `--branch main` (or the pipeline's branch variable) explicitly.
  • A Git-integrated Pages project needs a build step that must run in your own CI. What are the options?
    It cannot be converted to Direct Upload. Either turn off automatic production deployments and set previews to *None* in branch deployment controls, then deploy from CI with `wrangler pages deploy`, or create a new Direct Upload project and move the custom domains to it.

  • A Direct Upload project can be connected to a Git repository later.
  • Passing `--env production` to `wrangler pages deploy` makes it a production deployment.
  • Leaving out `--branch` always deploys to production.
  • CI needs an interactive `wrangler login` before it can deploy.
  • Pages can build directly from any Git host, including self-hosted ones.