Deploying a Static Website with GitHub and Cloudflare Pages
A practical, no-framework deployment workflow for a plain HTML and CSS site.
What this builds
This field note walks through a simple static website deployment for a project with a plain index.html and css/style.css inside a public/ directory. It also explains how GitHub pushes power Cloudflare Pages previews and a custom subdomain.
How the deployment flow works
Cloudflare Pages builds from a GitHub repository and publishes the contents of a chosen output directory. Feature branches receive preview deployments, while the main branch publishes the production site.
Prerequisites
- A plain HTML/CSS site in a local project.
- A GitHub account and a repository ready to receive the code.
- A Cloudflare account with Pages access.
Create the static site
Keep the site simple. Use a public/ output directory that contains a top-level index.html and a nested css/style.css.
index.html file for the published site.Put the project in GitHub
Prepare the static output before initializing Git, then create the repository locally, add the remote, and push.
mkdir public
cp index.html public/
mkdir -p public/css
cp css/style.css public/css/
git init
git add .
git commit -m "Initial static site"
git branch -M main
git remote add origin https://github.com/YOUR-USER/YOUR-REPO.git
git push -u origin mainIf the site already lives inside public/, the copy commands are unnecessary.
If your repository already exists, use the GitHub command line instructions to add locally hosted code to GitHub.
Connect the repository to Cloudflare Pages
Use the Pages setup flow and select GitHub integration. Choose the repository for YOUR-USER/YOUR-REPO.
Configure a custom subdomain
For a custom subdomain, set the Pages domain to the new hostname and associate it in Cloudflare Pages before relying on a DNS CNAME record.
This ensures Pages knows the subdomain is authorized for your site.
Use branch preview deployments
After commits are pushed to a non-production branch, Cloudflare Pages creates a preview deployment automatically. This lets you verify changes before merging to main.
git switch -c feature/button-update
git add public/css/style.css
git commit -m "Update button styles"
git push -u origin feature/button-updatePublish updates
Merge approved changes into main. Cloudflare Pages will deploy the production site from the main branch.
git switch main
git pull --ff-only origin main
git merge --ff-only feature/button-update
git push origin mainCache troubleshooting: new HTML with old CSS
If the published site shows updated HTML but still loads an older stylesheet, add a query string to the CSS reference in the page.
<link rel="stylesheet" href="css/style.css?v=0.3.0">This forces browsers to fetch the newest stylesheet while keeping the file path unchanged.
Final checklist
- Static site files are inside
public/. - Top-level
public/index.htmlexists. - GitHub repo is connected to Cloudflare Pages.
- Production branch is main.
- Build command is exit 0.
- Custom subdomain is associated before DNS changes.