Skip to content
~/hth
All notes
#CI/CD & GitOps

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 main unnoticed.

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 10000 both 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: curl must return 200.
  • Use concurrency so two pushes don’t deploy at the same time.
  • Share one deploy command between your machine and CI (npm run deploy:upload here), so they can’t drift apart.