← ./articles

Cloudflare Pages Git Integration or Direct Upload? Decide Before You Create the Project

cloudflare-pageswranglerdeploymentcistatic-site

Cloudflare Pages gives you two common deployment paths: Git integration and Direct Upload.

They sound like interchangeable ways to publish the same static site. In practice, the choice affects how you build, preview, promote, and troubleshoot the site. You should decide before creating the project.

The two paths

Git integration connects Pages to a GitHub or GitLab repository. Cloudflare runs the build when you push.

Direct Upload lets you build elsewhere and upload the final static directory with Wrangler:

npx wrangler pages deploy out --project-name my-site

Both can work. The trade-off is where build control lives.

Git integration is convenient

Git integration is a good fit when:

  • the project has a simple build
  • Cloudflare's build environment supports your Node version and toolchain
  • you want automatic preview deployments from branches or pull requests
  • you do not need much custom build orchestration

The downside is that debugging can move into the Cloudflare build environment. Node version, build command, output directory, environment variables, and monorepo root settings all have to match what your project expects.

Direct Upload gives you control

Direct Upload is a better fit when:

  • you want to build locally or in GitHub Actions
  • you need exact Node/npm versions
  • you have custom prebuild steps
  • your app is already static-exported into out/ or dist/
  • you want Cloudflare to only host the final artifact

The workflow becomes:

build outside Cloudflare
verify output directory
upload static files with Wrangler

For a Next.js static export, that can be:

npm run build
npx wrangler pages deploy out --project-name my-site

Production vs preview with Direct Upload

With Wrangler Direct Upload, be careful with branch flags.

For production:

npx wrangler pages deploy out --project-name my-site

Adding a branch flag can create a branch or preview deployment instead of the production alias you expected:

npx wrangler pages deploy out --project-name my-site --branch preview

That is useful when intentional. It is confusing when you expected the main Pages domain to update.

Decision checklist

Choose Git integration when:

  • the app is conventional
  • the build is simple
  • automatic branch previews matter most
  • you are comfortable configuring build settings in Cloudflare

Choose Direct Upload when:

  • build reproducibility matters more
  • you need custom Windows, npm, or static export preparation
  • you already have CI that produces a verified artifact
  • you want one command to upload exactly what you inspected

Summary

Cloudflare Pages deployment is not only a hosting choice. It is a workflow choice.

Git integration is convenient. Direct Upload is explicit. For projects with custom build steps or static-export verification, building outside Cloudflare and uploading with Wrangler is often easier to reason about.

References