This guide teaches a safer publishing workflow for static sites: create a branch, push it, validate the real preview, then merge to main. The goal is simple: catch deployment problems before they hit production.
If your site is hosted behind Cloudflare, a local preview is useful but incomplete. Local testing tells you whether the page works on your machine. A branch preview tells you whether the site works through the real deployment path: GitHub branch content, public URLs, asset loading, cache rules, and Cloudflare behavior.
Why Preview Branches Beat Local Testing for the Final Check
Local servers are fast, convenient, and still worth using. But they are not the final truth for a production-facing static site. Preview deployments are closer to reality because they run through the same path your visitors will use.
| Question | Local Server | Branch Preview | Main / Production |
|---|---|---|---|
| Fast iteration while building? | Yes | Slower | Wrong stage |
| Uses public hosted URLs? | No | Yes | Yes |
| Exposes Cloudflare-served asset behavior? | No | Yes | Yes |
| Safe place to catch mistakes before release? | Partly | Best option | Too late |
The practical rule is: local first for speed, preview second for truth, main last for release.
What Preview Branches Commonly Catch
Broken PNG or image paths
The browser requests the real deployed asset path. If the file name, case, or folder path is wrong, the preview exposes it fast.
Bad relative hyperlinks
A link that seems fine from a local root page can break on a real subpage once the deployed path matters.
Missing committed files
If you forgot to add a new HTML page, image, or asset to the branch, the preview returns the real failure instead of hiding it.
Stale JS or CSS cache-busting
Preview deployments reveal whether the live branch is actually serving the version you intended, especially after a shared asset bump.
Cloudflare routing behavior
Redirects, DNS-backed behavior, and host-level quirks show up here, not on a local Python server.
Desktop/mobile differences on public URLs
It is easier to test real page behavior across devices once the branch is online and shareable.
The Recommended Workflow
-
Create a new branch from main
Start from a clean main branch, then create a task-specific branch for the change. This keeps production safe while you build and gives the preview a focused purpose.
Use branch names that describe the change clearly, like review/new-guide or review/footer-fix. -
Make the changes on that branch
Build the page, update links, wire navigation, and fix related files while still in the isolated branch. Do your fast checks locally first so obvious breakage never reaches preview.
-
Push the branch to GitHub
Once the local pass is reasonably clean, push the branch. This is what makes the preview environment reflect the actual branch content instead of your workstation state.
The preview is only as good as the branch. If you forgot to add a file before pushing, the preview will surface that omission immediately. -
Open the preview deployment URL
Wait for the hosting platform to generate the branch preview, then load the public preview URL in a normal browser. This is the key validation step because it uses the live hosting and Cloudflare path.
-
Test like a visitor, not like a developer
Click through the real navigation. Open multiple pages. Load the preview on desktop and mobile. Treat it like a user would, because users do not browse your local server.
-
Fix anything the preview exposes and push again
If a PNG is broken, a relative link is wrong, or a footer reference is missing, fix it on the same branch and repush. The preview becomes the working QA surface until it is clean.
-
Merge to main only after the preview is clean
Once the preview behaves correctly, merge that branch to main. Main should be the promotion step, not the test environment.
That one change in mindset prevents a lot of avoidable production mistakes.
What to Check on the Preview Before You Merge
Core page checks
- Page loads without missing styles or scripts
- Hero images and PNG assets render correctly
- Title, description, and visible content match the new page
- Footer and nav links resolve without dead ends
- Subpages use correct relative asset paths
Deployment reality checks
- Branch preview URL is serving the expected commit
- Cache-busted CSS and JS versions are the intended ones
- Any new file is actually present in the deployed branch
- Desktop and mobile behavior both look right
- Nothing production-critical was left to test on main
Why This Matters More on Hand-Maintained Static Sites
When a site has many hardcoded HTML pages and relative paths, the margin for a small path mistake is much higher. A branch preview helps because it validates the real relationship between files once deployed. That makes it especially good at catching:
- Depth mistakes like ../ versus ../../
- Navigation drift where a new page was added in one place but not another
- Asset omissions where a new hero PNG was never committed
- Case mismatches that break on the deployed host
- Release boundary issues where a shared JS or CSS version did not roll the way you expected
Common Mistakes to Avoid
Using main as the test branch
If you merge first and inspect second, you are testing in production. That removes the safety buffer and makes every mistake public immediately.
Only checking the page you edited
Shared nav, footer, sitemap, or script changes often affect multiple pages. Preview testing should include the edited page plus a few neighboring pages that reuse the same shared pattern.
Trusting a local success too much
Local success means the idea is probably correct. It does not guarantee the hosted version is correct.
Using Cloudflare for Hosting and DNS?
Pair this preview workflow with a clean Cloudflare DNS setup so your branch testing and production path stay predictable.
Read the Cloudflare DNS Guide → Build Your Website Playbook →Frequently Asked Questions
Why is a preview branch better than local testing for the final check?
Because the preview uses the real deployment path: the branch content on GitHub, the hosting layer, public URLs, asset loading, and Cloudflare behavior. Local testing is still useful for quick iteration, but it does not fully reproduce production-like path resolution, cache behavior, or public asset delivery.
What issues do preview branches usually catch?
The most common issues are broken PNG or image paths, incorrect relative links, stale CSS or JS cache-busting, bad redirects, missing committed files, and pages that work locally but fail on public URLs.
Should I stop testing locally?
No. Local testing is still the fastest way to catch obvious layout and content issues while you build. The recommended workflow is local first for speed, preview second for deployment truth, and main last for release.
Do I need Cloudflare Pages to use this workflow?
You need some preview deployment system, but Cloudflare Pages is a strong fit for static sites because it gives you real hosted previews behind the same platform you use in production. The underlying principle works anywhere that supports branch previews.
When should I merge to main?
Merge only after the preview deployment is clean on the real public preview URL: core pages load, images render, nav works, relative links resolve, scripts load, and the page set behaves the way you expect across desktop and mobile.
Can preview testing catch missing files?
Yes. If you forgot to add a PNG, HTML file, or other asset to the branch before pushing, the preview is one of the fastest ways to expose it because the browser requests the real deployed file path and returns a visible 404 or broken asset.
