Saltar al contenido principal
Serie completa de Deploy Automático con Wrangler y GitHub Actions

Deploy Automático con Wrangler y GitHub Actions: Serie

20 de mayo de 2024 9 min de lectura
Compartir:

¿Quieres dominar el deploy automático con Wrangler y GitHub Actions? Esta serie completa te lleva desde la configuración inicial hasta el troubleshooting avanzado, creando un sistema CI/CD profesional paso a paso.

Lo que vas a dominar

Esta serie completa te enseña a crear un sistema de deploy automático profesional:

  • Configuración inicial de Wrangler y Cloudflare Pages
  • GitHub Actions CI/CD para deploy automático
  • Troubleshooting avanzado para WSL y problemas comunes
  • Workflow completo de desarrollo profesional
  • Mejores prácticas de DevOps y automatización

Serie Completa: 3 Guías Especializadas

Parte 1: Configuración Inicial

Configurar Wrangler y Cloudflare Pages: Guía Completa 2024

Aprende la configuración base:

  • Instalación y autenticación de Wrangler
  • Creación de proyectos en Cloudflare Pages
  • Configuración de wrangler.toml
  • Primer deploy manual
  • Soluciones para WSL

Tiempo: ~5 minutos de lectura | Nivel: Principiante

Parte 2: Automatización CI/CD

GitHub Actions para Deploy Automático: CI/CD con Wrangler

Automatiza tus deploys:

  • Creación de API tokens en Cloudflare
  • Configuración de GitHub Secrets
  • Workflow de GitHub Actions
  • Deploy automático en push
  • Monitoreo y verificación

Tiempo: ~6 minutos de lectura | Nivel: Intermedio

Parte 3: Troubleshooting Avanzado

Troubleshooting Wrangler: Soluciones para WSL y Deploy Issues

Resuelve problemas comunes:

  • Errores de binarios en WSL
  • Problemas de autenticación
  • Issues en GitHub Actions
  • Errores de deploy y configuración
  • Herramientas de diagnóstico

Tiempo: ~4 minutos de lectura | Nivel: Avanzado

Ruta de Aprendizaje Recomendada

Para Principiantes

  1. Parte 1: Configuración - Empieza aquí
  2. Parte 2: CI/CD - Automatiza
  3. Parte 3: Troubleshooting - Domina

Para Desarrolladores con Experiencia

Prerrequisitos para la Serie

  • Proyecto web funcionando localmente (Astro, React, Vue, etc.)
  • Cuenta de Cloudflare (gratuita está bien)
  • Repositorio en GitHub
  • Node.js y npm instalados
  • Conocimientos básicos de Git y terminal

Resumen de la Serie

Parte 1: Configuración Base

Configurar Wrangler y Cloudflare Pages

Lo que aprenderás:

  • Instalación y autenticación de Wrangler
  • Creación de proyectos en Cloudflare Pages
  • Configuración de wrangler.toml
  • Primer deploy manual exitoso
  • Soluciones específicas para WSL

Puntos clave:

  • Usar npx wrangler en WSL para evitar problemas
  • Guardar Account ID para GitHub Actions
  • Configurar pages_build_output_dir correctamente

Parte 2: Automatización CI/CD

GitHub Actions para Deploy Automático

Lo que aprenderás:

  • Crear API tokens con permisos correctos
  • Configurar GitHub Secrets de forma segura
  • Crear workflows de GitHub Actions
  • Deploy automático en cada push
  • Monitoreo y verificación de deploys

Puntos clave:

  • API tokens con permisos mínimos necesarios
  • Secrets seguros en GitHub
  • Cache de npm para builds rápidos

Parte 3: Troubleshooting

Soluciones para WSL y Deploy Issues

Lo que aprenderás:

  • Resolver errores de binarios cruzados
  • Solucionar problemas de autenticación
  • Debuggear issues en GitHub Actions
  • Herramientas de diagnóstico
  • Mejores prácticas de desarrollo

Puntos clave:

  • Checklist completo de troubleshooting
  • Comandos de diagnóstico útiles
  • Workflow optimizado de desarrollo

Beneficios de Completar la Serie

Para Desarrolladores

  • Deploy en 1-2 minutos desde push hasta producción
  • Seguridad profesional con tokens y secrets apropiados
  • Monitoreo completo con GitHub Actions
  • CDN global de Cloudflare automático
  • Rollback fácil si algo falla

Para Equipos

  • Workflow estandarizado para todo el equipo
  • Documentación completa para onboarding
  • Productividad aumentada con automatización
  • ️ Menos errores con proceso automatizado
  • Escalabilidad para proyectos grandes

Para Proyectos

  • ️ Infraestructura como código con GitHub Actions
  • Mantenimiento simplificado con configuración centralizada
  • Métricas de deploy y monitoreo integrado
  • Performance global con Cloudflare Edge Network

Comienza tu Journey de Deploy Automático

¿Por dónde empezar?

Si eres nuevo en Wrangler: Parte 1: Configurar Wrangler y Cloudflare Pages

Si ya tienes Wrangler configurado: Parte 2: GitHub Actions para Deploy Automático

Si tienes problemas o errores: Parte 3: Troubleshooting Wrangler

Lo que lograrás al completar la serie

Infraestructura Profesional

  • Deploy automático en 1-2 minutos
  • Seguridad con tokens y secrets
  • Monitoreo completo con GitHub Actions
  • CDN global de Cloudflare
  • Rollback fácil si algo falla

Workflow Optimizado

  • Push to deploy automático
  • 🧪 Testing integrado en CI/CD
  • Preview deployments para PRs
  • Métricas y logs detallados

Conceptos Clave de la Serie

Wrangler + WSL

  • Usar npx wrangler para evitar problemas de binarios
  • Configuración correcta de wrangler.toml
  • Autenticación y gestión de proyectos

GitHub Actions CI/CD

  • API tokens con permisos mínimos
  • Secrets seguros en GitHub
  • Workflows optimizados con cache
  • Deploy automático en push a main

Troubleshooting

  • Diagnóstico de errores comunes
  • Herramientas de debugging
  • Mejores prácticas de desarrollo
  • Checklist completo de verificación

Próximos Pasos en tu Journey DevOps

3.1 Crear el Workflow

Crea el directorio y archivo:

mkdir -p .github/workflows

Crea .github/workflows/deploy.yml:

name: Deploy to Cloudflare Pages

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

jobs:
  deploy:
    runs-on: ubuntu-latest

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

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

    - name: Install dependencies
      run: npm ci

    - name: Build project
      run: npm run build

    - name: Deploy to Cloudflare Pages
      uses: cloudflare/pages-action@v1
      with:
        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
        projectName: tu-proyecto
        directory: dist

3.2 Crear API Token en Cloudflare

Paso 1: Ir al Dashboard

Paso 2: Configurar Token Personalizado

  • Seleccionar “Custom token”
  • Token name: GitHub-Actions-TuProyecto
  • Permissions:
    • Account → Cloudflare Pages:Edit
    • Zone → Zone:Read (opcional)
  • Account Resources: Include → Tu Cuenta Específica

Paso 3: Crear y Copiar Token

  • Click “Continue to summary”
  • Click “Create Token”
  • ️ CRÍTICO: Copia el token INMEDIATAMENTE (solo se muestra una vez)

3.3 Configurar Secrets en GitHub

  • Ir a tu repositorio en GitHub
  • Settings → Secrets and variables → Actions
  • Click “New repository secret”

Agregar los Secrets

  1. CLOUDFLARE_ACCOUNT_ID

    • Name: CLOUDFLARE_ACCOUNT_ID
    • Secret: Tu Account ID de Cloudflare

  2. CLOUDFLARE_API_TOKEN

    • Name: CLOUDFLARE_API_TOKEN
    • Secret: El token que copiaste

GitHub Repository Secrets configurados correctamente

Así se ven los secrets correctamente configurados en GitHub. Ambos secrets son necesarios para el deploy automático.

FASE 4: Scripts de Deploy Optimizados

Agrega estos scripts a tu package.json:

{
  "scripts": {
    "build": "astro build",
    "deploy": "npm run build && npx wrangler pages deploy dist --project-name=tu-proyecto --commit-dirty=true",
    "deploy:clean": "npm run build && npx wrangler pages deploy dist --project-name=tu-proyecto",
    "deploy:ci": "wrangler pages deploy dist --project-name=tu-proyecto",
    "pages:list": "npx wrangler pages project list",
    "wrangler:login": "npx wrangler login"
  }
}

Explicación de Scripts

  • deploy: Desarrollo rápido (permite cambios sin commit)
  • deploy:clean: Producción (requiere commits limpios)
  • deploy:ci: Para GitHub Actions
  • pages:list: Listar proyectos existentes
  • wrangler:login: Re-autenticación cuando sea necesario

FASE 5: Primer Deploy y Verificación

5.1 Probar Deploy Manual

# Primer deploy manual para verificar configuración
npm run deploy

Salida esperada:

 Compiled successfully.
 Uploading... (X files)
 Success! Uploaded X files (X.XX sec)
 Deploying...
 Deployment complete! Take a peek over at https://xxxxxxxx.tu-proyecto.pages.dev

5.2 Activar Deploy Automático

# Commit y push para activar GitHub Actions
git add .
git commit -m " Configure deploy automation

 Added wrangler.toml configuration
 Added GitHub Actions workflow
 Added deploy scripts to package.json
 Ready for automatic deployment"

git push origin main

5.3 Monitorear el Deploy

  1. Ir a: https://github.com/tu-usuario/tu-proyecto/actions
  2. Ver el workflow ejecutándose
  3. Verificar cada paso:
    • Checkout
    • Setup Node.js
    • Install dependencies
    • Build project
    • Deploy to Cloudflare Pages

GitHub Actions workflow ejecutándose exitosamente

El workflow de GitHub Actions ejecutándose correctamente. Puedes ver el estado “Deploy automático configurado” y el tiempo de ejecución (~1m 5s).

️ Troubleshooting Completo

Error de Binarios WSL

Síntoma:

Error: You installed workerd on another platform...

Solución:

# Limpiar instalaciones
rm -rf node_modules package-lock.json
npm install

# Usar siempre npx
npx wrangler --version  #  Funciona
wrangler --version      #  Puede fallar

Error de Autenticación

Síntoma:

Error: Authentication required

Solución:

# Re-autenticar
npx wrangler login
npx wrangler whoami

Error en GitHub Actions

Diagnóstico:

  • Verificar secrets en GitHub
  • Verificar permisos del API token
  • Revisar logs en GitHub Actions

Solución:

# Verificar Account ID
npx wrangler whoami

# Recrear secrets si es necesario
# GitHub → Settings → Secrets → Actions

Workflow Completo de Desarrollo

Para Desarrollo Diario

# 1. Desarrollo local
npm run dev

# 2. Deploy rápido para testing
npm run deploy

# 3. Si está bien, deploy a producción
git add .
git commit -m "feat: nueva funcionalidad"
git push origin main  # Deploy automático

Para Features Grandes

# 1. Crear branch
git checkout -b feature/nueva-funcionalidad

# 2. Desarrollar y probar
npm run dev
npm run deploy  # Preview

# 3. Merge a main
git checkout main
git merge feature/nueva-funcionalidad
git push origin main  # Deploy automático

Verificación Visual del Setup

Secrets Configurados Correctamente

Como puedes ver en la primera imagen, los secrets de GitHub deben estar configurados exactamente así:

  • CLOUDFLARE_ACCOUNT_ID - Tu Account ID de Cloudflare
  • CLOUDFLARE_API_TOKEN - El token con permisos de Cloudflare Pages

Workflow Funcionando

La segunda imagen muestra el workflow ejecutándose exitosamente:

  • Estado: Deploy automático configurado
  • ⏱️ Tiempo: ~1m 5s (muy rápido!)
  • Trigger: Push a main branch
  • Commit: Mensaje descriptivo del deploy

Beneficios Obtenidos

Infraestructura Completa

  • Deploy automático en cada push a main
  • Deploy manual para desarrollo rápido
  • GitHub Actions CI/CD completamente configurado
  • Resolución de problemas WSL implementada

Workflow Profesional

  • Deploy en ~1-2 minutos desde push
  • Seguridad con tokens y secrets apropiados
  • Monitoreo completo con GitHub Actions
  • CDN global de Cloudflare automático
  • Rollback fácil si algo falla

Próximos Pasos

  1. Configurar dominio personalizado en Cloudflare Pages
  2. Implementar preview deployments para Pull Requests
  3. Agregar notificaciones de deploy (Slack, Discord)
  4. Configurar métricas y monitoreo avanzado

Lecciones Clave

  1. WSL + Wrangler: Siempre usar npx wrangler para evitar problemas
  2. Secrets Management: Usar GitHub Secrets, nunca commitear credenciales
  3. CI/CD Optimization: npm ci + cache acelera builds significativamente
  4. Documentation: Documentación clara es esencial para mantenimiento

Conclusión

Has implementado exitosamente un sistema de automatización de despliegues profesional que:

  • Funciona de manera consistente en cualquier entorno
  • Escala para equipos de cualquier tamaño
  • Incluye todas las mejores prácticas DevOps de la industria
  • Está completamente documentado para futuro mantenimiento
  • Proporciona un flujo CI/CD robusto y confiable

Este setup de integración continua te servirá como base para cualquier proyecto futuro con Astro y Cloudflare Pages.

Próximos Pasos en tu Journey DevOps

¿Te gustó este tutorial de automatización de despliegues? Continuá optimizando tu flujo de trabajo:

Tutoriales Relacionados:

️ Explora más sobre Automatización DevOps:

¿Qué automatizar después?

  • Testing automático con Vitest y GitHub Actions
  • Optimización de imágenes en el pipeline CI/CD
  • Notificaciones de deploy en Slack/Discord
  • Métricas y monitoreo automatizado

¿Te ha resultado útil este tutorial de deploy continuo? ¡Compártelo y ayuda a otros desarrolladores a configurar su automatización de despliegues!

Enlace copiado al portapapeles