cloudflare-pages-cicd

license	Apache-2.0
name	cloudflare-pages-cicd
description	Cloudflare Pages CI/CD with preview environments, edge functions, and Wrangler automation. Activate on: Cloudflare Pages, Wrangler deploy, preview environment, edge function, Pages project, Cloudflare Workers integration, custom domain on Pages. NOT for: Worker-specific development (use cloudflare-worker-dev), DNS management (use devops-automator), full-stack app frameworks (use vercel-deployment).
allowed-tools	Read,Write,Edit,Bash(docker:*,kubectl:*,terraform:*,npm:*,npx:*)
category	DevOps & Infrastructure
tags	["cloudflare","ci-cd","edge","deployment"]
pairs-with	[{"skill":"cloudflare-worker-dev","reason":"Workers and Pages share the Cloudflare platform; Pages Functions are Workers under the hood"},{"skill":"ci-cache-optimizer","reason":"Build caching strategies apply to Cloudflare Pages builds"}]

Cloudflare Pages CI/CD

Expert in deploying and automating Cloudflare Pages projects with preview environments, edge functions, and Wrangler CLI.

Decision Points

Compute Platform Selection

Request processing needs:
├─ Static assets only → Pages (no functions needed)
├─ <10ms CPU + simple API routes → Pages Functions
├─ 10-50ms CPU + stateful operations → Workers
└─ >50ms CPU or heavy processing → Queues + Workers

Deployment model:
├─ Git-based with previews → Pages Git integration
├─ CI/CD with artifact upload → `wrangler pages deploy`
├─ Local development testing → `wrangler pages dev`
└─ Multi-environment promotion → Direct upload with branch targeting

Build Configuration Strategy

Framework detected:
├─ Next.js → Use @cloudflare/next-on-pages adapter
├─ Astro/SvelteKit/Remix → Native Cloudflare support
├─ Static site generator → Standard build command
└─ Custom build → Specify exact build command + output dir

Environment variables needed:
├─ Public vars → [vars] in wrangler.toml
├─ Secrets → `wrangler pages secret put`
├─ Preview-specific → Environment-based binding IDs
└─ Build-time only → CI/CD environment variables

Binding Architecture

Data persistence requirements:
├─ Cache/sessions → KV (global, eventual consistency)
├─ Relational data → D1 (SQL, strong consistency per location)
├─ File storage → R2 (S3-compatible object storage)
├─ Real-time state → Durable Objects
└─ External APIs → Service bindings or fetch()

Preview environment isolation:
├─ Development → Separate binding IDs for all resources
├─ Staging → Shared read-only or staging-specific resources  
├─ Production → Live binding IDs
└─ Local dev → `--local` flag with local SQLite/memory KV

Failure Modes

Build Timeout Death Spiral

Symptoms: Builds consistently timeout at 20+ minutes, "Build exceeded time limit" Root cause: Inefficient dependency installation or missing build cache Fix:

• Add node_modules caching in CI/CD
• Use npm ci instead of npm install
• Enable Wrangler's incremental uploads with --no-bundle Detection: grep "Build exceeded" build-logs.txt

Environment Variable Mismatch

Symptoms: Functions work locally but fail in production with "undefined is not a function" Root cause: Missing environment variables or incorrect binding names Fix:

• Verify wrangler.toml matches dashboard bindings exactly