Cloudflare Pages with GitHub is pleasant when the flow is boring: edit, push, wait, verify. It becomes chaotic when a build error leads to a DNS change, which leads to a dependency change, leaving three unrelated failures stacked together.
Keep four objects separate
- The source repository stores code and history.
- The production branch, often
main, selects production changes. - The Pages project receives the built output.
- The custom domain routes visitors to that project.
A successful push is not a successful build. A successful build does not prove the custom domain is healthy. Correct DNS cannot invent a missing index.html.
Isolation matters more than cleverness
Give an independent site a clear repository or directory and one unambiguous Pages target. Do not upload an article build to a game project or reuse unrelated Worker, KV or database bindings.
Git integration or a protected workflow
Native Git integration builds the production branch automatically and can create preview deployments for other branches. It is ideal for a straightforward static site.
A GitHub Actions workflow can build first and use Wrangler to deploy an exact directory. That allows target guards and post-deployment checks, but the workflow becomes another maintained component. Choose one documented production path; mixing automatic builds and ad-hoc direct uploads makes the live version difficult to trace.
Create a rollback point first
Record the currently healthy commit SHA and create a branch or tag when the change deserves one. Descriptive commit messages are part of recovery. A history containing only “update” and “fix” is almost useless during an incident.
Build command and output directory are a pair
If npm run build writes to dist, the deployment must upload dist. Validate the home page, internal links, sitemap, robots, 404, asset paths and absence of accidental secrets before uploading.
Diagnose the failing stage
Dependency installation
Inspect the runtime version, lockfile and registry. DNS is not the first suspect.
Build
Read the first compiler error, missing file or environment value. The previous successful deployment normally remains online.
Upload
Check token permissions, account ID, project name and directory.
Custom domain after a successful deployment
Open the generated pages.dev deployment. If it works, investigate the domain, certificate and DNS. If it fails too, stay in the build or project layer. The DNS lookup guide explains the relevant records.
Rollback to something known
A successful Pages production deployment is a valid rollback target. Use a known deployment or commit, not a vaguely named ZIP from a laptop. After rollback, verify the custom domain, a deep link, assets, the 404 response and one critical interaction.
Cache deliberately
HTML rarely belongs under a year-long immutable cache. Fingerprinted or explicitly versioned CSS and JavaScript can use long caching. Reusing an asset URL after changing its contents creates the classic “I definitely deployed this” illusion.
Confirm target, create rollback point, build and check, push, verify deployment, verify production. Reliable publishing should feel uneventful.
Official references: Pages Git integration · Pages rollbacks