Deploying to Cloudflare Pages from GitHub Actions
The pipeline behind this site, and the two mistakes that cost me time. One was the wrong token permission, the other was deploying to the wrong branch.
Written Nov 21, 20262 min read
- GitHub Actions
- Cloudflare Pages
- Wrangler
- CI/CD
On this page
Setup
The Pages project uses Direct Upload: Cloudflare doesn’t build anything. GitHub Actions builds the site and uploads dist/ with Wrangler.
- Push to
main:npm ci→npm run build→ deploy to production → smoke test. - Pull request: build only, so broken code never reaches
mainunnoticed.
The deploy step:
- name: Deploy to Cloudflare Pages
run: npx wrangler pages deploy dist --project-name hth-portfolio --branch production
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
Mistake 1: the token could only read
The deploy failed with:
A request to the Cloudflare API (/accounts/***/pages/projects/hth-portfolio/upload-token) failed.
Authentication error [code: 10000]
My token had Cloudflare Pages: Read, plus two unrelated permissions (Account Custom Pages and Access: Custom Pages). Type “Pages” in the permission picker and all three show up, and the last dropdown defaults to Read.
What deploying actually needs is one line: Account → Cloudflare Pages → Edit, scoped to the account that owns the project.
Two things that misled me:
- Wrangler printed Super Administrator - All Privileges. That’s my role on the account, not what the token is allowed to do.
- Cloudflare returns code
10000both for an invalid token and for a valid token without permission. The token summary page is the fastest way to tell which one it is.
Mistake 2: deploys landed in Preview
A Pages project has one production branch, chosen when the project is created. Wrangler suggested production. Without --branch, Wrangler uses the current git branch. In a repo on main, every deploy became a preview (alias main.<project>.pages.dev) and the live site didn’t change.
The fix is to always pass --branch <production-branch> and check where a deploy went:
npx wrangler pages deployment list --project-name hth-portfolio
# The Environment column must say Production
Worth keeping in every pipeline
- Pin third-party actions to a commit SHA, with the version in a comment.
- Fail early with a clear message when a secret is missing.
- Smoke test the live URL after deploying:
curlmust return200. - Use
concurrencyso two pushes don’t deploy at the same time. - Share one deploy command between your machine and CI (
npm run deploy:uploadhere), so they can’t drift apart.