Deploy en Cloudflare Pages con GitHub Actions

Cloudflare Pages tiene algo que la mayoría de plataformas de hosting no tiene: CDN global incluido desde el primer request, sin coste adicional. Este tutorial te conecta de GitHub a producción con deploys automáticos en cada push.

Funciona para sitios estáticos (HTML/CSS/JS), frameworks modernos (Next.js, Astro, SvelteKit, Nuxt) y apps con server-side rendering usando Cloudflare Workers por detrás.

Paso 1: Preparar el repositorio

Tu proyecto necesita un comando de build y un directorio de salida definidos. Verifica que funcionen localmente:

npm run build
# El directorio de salida suele ser: dist/, out/, .next/, _site/

Si no tienes un package.json claro, aquí va uno mínimo para un proyecto Astro como ejemplo:

{
  "scripts": {
    "build": "astro build",
    "preview": "astro preview"
  }
}

Asegúrate de que el .gitignore incluye node_modules/ y el directorio de build. No subas builds al repo — Cloudflare los generará en cada deploy.

Paso 2: Crear el proyecto en Cloudflare Pages

1. Entra a dash.cloudflare.com y ve a Workers & Pages
2. Haz clic en Create application → Pages → Connect to Git
3. Autoriza Cloudflare para acceder a tu cuenta de GitHub
4. Selecciona el repositorio que quieres desplegar

En la pantalla de configuración de build:

Campo	Valor
Framework preset	Selecciona tu framework (Astro, Next.js, etc.)
Build command	npm run build
Build output directory	dist (o el de tu framework)
Root directory	/ (salvo que tu proyecto esté en una subcarpeta)

Haz clic en Save and Deploy. El primer build tarda 1-3 minutos.

Paso 3: Configurar variables de entorno

Si tu proyecto usa variables de entorno (claves de API, URLs de base de datos), añádelas antes de que el build las necesite:

En Cloudflare Pages → Settings → Environment variables:

NODE_ENV=production
PUBLIC_API_URL=https://api.tudominio.com
DATABASE_URL=postgresql://...

Las variables con prefijo PUBLIC_ o NEXT_PUBLIC_ (según el framework) se exponen al cliente. Las demás solo están disponibles en el servidor.

Nunca subas claves al repositorio. Cloudflare cifra las variables de entorno y no las expone en los logs de build.

Paso 4: GitHub Actions para control avanzado

El deploy automático por push ya funciona desde Paso 2. Pero si quieres control adicional (tests antes del deploy, notificaciones, deploys condicionales), añade GitHub Actions:

Crea .github/workflows/deploy.yml:

name: Deploy a Cloudflare Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Instalar dependencias
        run: npm ci

      - name: Tests
        run: npm test --if-present

      - name: Build
        run: npm run build
        env:
          PUBLIC_API_URL: ${{ secrets.PUBLIC_API_URL }}

      - name: Deploy a Cloudflare Pages
        uses: cloudflare/pages-action@v1
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: nombre-de-tu-proyecto
          directory: dist
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          branch: main

Paso 5: Obtener las credenciales de Cloudflare

El workflow necesita dos secrets de Cloudflare:

CLOUDFLARE_API_TOKEN:

1. Ve a cloudflare.com → My Profile → API Tokens
2. Create Token → Use template: “Cloudflare Pages”
3. Copia el token generado

CLOUDFLARE_ACCOUNT_ID:

• Aparece en el sidebar derecho de cualquier página de Workers & Pages en el dashboard

Añade ambos como secrets en GitHub: Settings → Secrets and variables → Actions → New repository secret.

Paso 6: Dominio personalizado

Si tienes un dominio propio, conéctalo en menos de 5 minutos:

1. Cloudflare Pages → tu proyecto → Custom domains → Set up a custom domain
2. Escribe tudominio.com o app.tudominio.com
3. Si tu dominio ya está en Cloudflare (nameservers apuntando a Cloudflare), el registro DNS se añade automáticamente
4. Si no, te da el registro CNAME para añadir en tu registrador

SSL se configura automáticamente. No necesitas certificados manuales.

Verificar que todo funciona

Haz un push de prueba al main:

git add .
git commit -m "test: verificar deploy automático"
git push origin main

Deberías ver:

• En GitHub Actions: el workflow corriendo con los pasos definidos
• En Cloudflare Pages: un nuevo deployment apareciendo en la lista
• En tu dominio: los cambios reflejados en 30-60 segundos

Si el build falla, los logs están en Cloudflare Pages → tu proyecto → el deployment fallido → View build log. Son más detallados que los de Vercel para depurar errores de dependencias.

Preview deployments en pull requests

Una función que vale la pena activar: Cloudflare Pages genera automáticamente una URL de preview única para cada pull request. Antes de mergear, puedes ver la versión de producción exacta en una URL como pr-45.tu-proyecto.pages.dev.

Esto viene activado por defecto. No necesitas configurarlo.

Límites del plan gratuito

Recurso	Plan gratuito
Requests	100,000 por día
Builds	500 por mes
Bandwidth	Sin límite
Sitios	Ilimitados
Dominios personalizados	Ilimitados

Para la mayoría de proyectos indie y startups en etapa inicial, el plan gratuito es suficiente durante meses o años.