Migrar el flujo de despliegue: Workers Builds o GitHub Actions · Cloudflare

Un proyecto migrado que solo se despliega desde el portátil de una persona no está migrado del todo. La comodidad de Pages nunca fue únicamente su hosting: era que conectabas un repositorio y a partir de ahí el sistema construía y publicaba solo, con una URL por rama para enseñar el trabajo antes de fusionarlo. Reproducir eso en Workers es la mitad menos vistosa de la convergencia y la que más afecta al día a día del equipo. Hay dos caminos, y no compiten en calidad sino en cuánto control quieres y cuánta responsabilidad estás dispuesto a asumir a cambio. Esta lección explica qué hacía el flujo antiguo, cómo se reconstruye con cada camino, y con qué criterio se elige.

🎯 Al terminar esta lección sabrás

Descomponer qué hacía exactamente el build automático de Pages en cada push.
Configurar Workers Builds para reproducir ese flujo dentro de la plataforma.
Escribir un flujo de GitHub Actions que despliegue con un token de alcance limitado.
Elegir entre ambos con criterios de control, verificación previa y recuperación.

Qué hacía el build automático

Lo primero que hay que hacer con una comodidad heredada es descomponerla, porque nadie puede reproducir lo que percibe como una sola cosa. Y el flujo de Pages no era una cosa: eran cuatro encadenadas con tanta suavidad que se sentían como un único gesto.

Conviene descomponer la magia antes de reproducirla, porque el flujo de Pages encadenaba cuatro cosas distintas que la gente percibía como una sola. Primero, escuchaba el repositorio y reaccionaba a cada push. Segundo, ejecutaba el comando de build en un entorno limpio, con la versión de tiempo de ejecución que hubieras fijado. Tercero, publicaba el resultado: producción si el push iba a la rama principal, previsualización si iba a cualquier otra. Y cuarto, comentaba en la solicitud de cambios con la URL resultante, que era el detalle que hacía que el equipo entero lo notara.

Cualquier sustituto tiene que cubrir esas cuatro funciones. Si al migrar solo reproduces el despliegue a producción y pierdes las previsualizaciones, habrás recuperado la publicación y perdido el ciclo de revisión, que es donde estaba la mayor parte del valor.

Conviene además nombrar lo que ese flujo no hacía, porque marca el límite de lo que estás reproduciendo. No ejecutaba tus pruebas ni tu comprobación de tipos como condición para publicar: si el build terminaba, se desplegaba. No distinguía entre publicar una versión y activarla, de modo que llegar a producción era un acto único e irreversible salvo por un nuevo despliegue. Y no ofrecía ninguna forma de repartir tráfico entre dos versiones para observar la nueva antes de comprometerse. Esas tres ausencias son precisamente lo que el segundo camino de esta lección permite añadir, y por eso migrar el despliegue no tiene por qué ser solo una traducción: puede ser una mejora.

flowchart TD
G[Push al repositorio] --> B[Entorno limpio de build]
B --> C{Rama principal}
C -->|si| P[Despliegue a produccion]
C -->|no| V[Version de previsualizacion con URL propia]
V --> R[Aviso en la solicitud de cambios]
style P fill:#a6e3a1,color:#11111b
style V fill:#89b4fa,color:#11111b

Workers Builds: el camino gestionado

Con las cuatro funciones nombradas, el primer camino es el que las reproduce sin pedirte nada a cambio.

Workers Builds es el equivalente directo dentro de la plataforma. Conectas el repositorio al Worker, declaras el comando de build y el comando de despliegue, y a partir de ahí cada push produce una versión. La rama principal publica a producción; el resto genera versiones de previsualización con su propia URL. Es el camino que replica la experiencia de Pages con la menor cantidad de piezas móviles.

La configuración vive junto al resto del proyecto y se reduce a decir qué hay que ejecutar:

{
  "name": "mi-app",
  "main": "src/index.ts",
  "compatibility_date": "2026-03-01",
  "assets": { "directory": "./dist" },
  "build": {
    "command": "npm ci && npm run build"
  },
  "observability": { "enabled": true }
}

La ventaja es que no administras credenciales ni corredores de integración continua: la plataforma ya sabe quién eres y a qué cuenta despliega. Eso elimina de un plumazo el activo más peligroso de cualquier tubería, que es un token de despliegue guardado en un sistema de terceros al que muchas personas pueden enviar código.

La limitación es la contrapartida natural de cualquier sistema gestionado: el entorno de build es el que hay, y si tu proyecto necesita pasos exóticos antes de publicar, acabarás peleándote con la caja en lugar de usarla. La frontera práctica está en si tu build cabe en un comando. Instalar dependencias y ejecutar una herramienta cabe; generar un artefacto en otro repositorio, esperar a que termine un proceso externo o pedir la aprobación de una persona, no.

GitHub Actions: el camino con control

El segundo camino es ejecutar tú mismo el despliegue desde tu integración continua. Aquí el despliegue deja de ser un servicio y pasa a ser un paso más de una tubería que tú diseñas, junto a los tipos, las pruebas y los linters. Es el camino adecuado cuando el despliegue debe ser la consecuencia de que algo haya pasado antes, y no simplemente de que alguien haya hecho push.

El ejemplo usa GitHub Actions porque es lo más extendido, pero nada de lo esencial depende de esa herramienta concreta: el patrón es instalar, verificar, construir y ejecutar el comando de despliegue con unas credenciales de alcance limitado, y eso se traduce igual a cualquier otro sistema de integración continua.

name: desplegar
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npm run typecheck && npm test
      - run: npm run build
      - run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Ese flujo hace algo que el build de Pages no hacía y conviene subrayar: coloca la comprobación de tipos y las pruebas antes del despliegue, de modo que publicar deja de ser la consecuencia automática de haber hecho push y pasa a ser la consecuencia de que el proyecto esté sano. Es un cambio de significado, no solo de herramienta.

La pieza delicada es el token. Créalo con el alcance mínimo necesario para editar Workers en esa cuenta, nunca con permisos globales, y guárdalo como secreto del repositorio. Un token de despliegue con permisos de más es una de las escaladas de privilegio más habituales y menos vigiladas de cualquier organización: vive en un sistema al que muchas personas pueden enviar código.

Un detalle que se olvida a menudo: fija la versión del tiempo de ejecución de tu entorno de build de forma explícita, como en el ejemplo. Un flujo que usa la versión por defecto del corredor cambia de comportamiento el día que esa versión por defecto cambia, y ese es el tipo de fallo que aparece de madrugada, sin que nadie haya tocado el código, y cuesta horas de diagnosticar porque el repositorio está idéntico.

Para reproducir las previsualizaciones, el mismo flujo puede reaccionar a las solicitudes de cambios y publicar una versión sin promoverla a producción:

npx wrangler versions upload
npx wrangler versions deploy

El primer comando sube una versión y devuelve su URL de previsualización sin tocar el tráfico real. El segundo promueve una versión concreta a producción, y admite hacerlo de forma gradual, repartiendo el tráfico entre la versión nueva y la anterior. Esa separación entre subir y promover es exactamente lo que Pages no ofrecía y es el argumento más fuerte a favor de este camino.

Cómo elegir entre los dos

La elección no se hace por preferencia estética sino respondiendo a unas pocas preguntas concretas sobre cómo trabaja tu equipo. Y no es excluyente: nada impide usar Workers Builds para los proyectos sencillos de la organización y una tubería propia para el que tiene pruebas de integración y aprobaciones.

Pregunta	Workers Builds	GitHub Actions
Quién administra las credenciales	La plataforma, sin token propio	Tú, con un token de alcance limitado
Qué se ejecuta antes de desplegar	El comando de build que declares	Cualquier paso: tipos, pruebas, linters, aprobaciones
Qué pasa si el proyecto es un monorepo	Un Worker por conexión	Un flujo que despliega varios Workers
Cuánto tardas en tenerlo funcionando	Minutos	Una tarde la primera vez
Qué mantienes tú a largo plazo	Nada	El flujo, sus versiones y sus permisos

🧰

Elige lo gestionado si el build es un comando

Si construir tu proyecto se reduce a instalar dependencias y ejecutar un comando, Workers Builds cubre el caso sin que administres nada. Es el equivalente honesto de la experiencia de Pages.

🔒

Elige tu tubería si el despliegue es una consecuencia

Si publicar debe depender de que las pruebas pasen, de que alguien apruebe o de que otro artefacto exista, necesitas un lugar donde expresar esa condición. Ese lugar es tu integración continua.

🧪

En ambos casos, separa subir de activar

La distinción entre publicar una versión y promoverla no depende del camino elegido. Adóptala desde el principio: es la diferencia entre un despliegue reversible y un salto.

💡

Empieza por lo gestionado y muévete cuando duela

La elección no es irreversible ni conviene tomarla por anticipado. Si tu proyecto se construye con un comando y se despliega con otro, Workers Builds te da el flujo de Pages sin administrar nada, y esa es la respuesta correcta hasta que deje de serlo. Muévete a tu propia tubería cuando aparezca una razón concreta y nombrable: pruebas que deben bloquear el despliegue, un artefacto que se construye en otro sitio, un monorepo con varios Workers, una aprobación manual antes de producción. Migrar el despliegue el día que tengas ese motivo cuesta una tarde; adelantarlo sin motivo te obliga a mantener una tubería para siempre.

⚡

El despliegue es la única parte de tu arquitectura que se ejecuta con permisos de todo

Hay una asimetría en cómo los equipos reparten su atención que se vuelve evidente en cuanto se examina un incidente de seguridad real. Dedicamos revisiones exhaustivas al código que atiende peticiones, donde cada entrada se valida y cada permiso se comprueba, y aceptamos con una ligereza asombrosa una tubería de despliegue que se ejecuta con credenciales capaces de reemplazar ese mismo código por cualquier otro. El sistema que puede sustituir tu aplicación entera es, por definición, más privilegiado que tu aplicación, y sin embargo suele estar peor auditado, definido en un archivo que nadie relee, y autenticado con un token que se creó una tarde con más permisos de los necesarios porque acotarlo daba pereza. Quien controla el despliegue no necesita encontrar un fallo en tu lógica: simplemente despliega otra lógica. Esto tiene tres consecuencias que conviene interiorizar antes de escribir el primer flujo. La primera es que el principio de mínimo privilegio se aplica al despliegue con más severidad que a ninguna otra parte del sistema, porque es donde el radio de daño es total; un token debe poder editar exactamente los Workers que edita y nada más. La segunda es que la tubería es código de producción y merece el mismo trato: se revisa, se versiona, se razona sobre quién puede modificarla y qué ocurre si alguien la modifica sin que nadie mire. Y la tercera, la más constructiva, es que separar la publicación de la activación cambia la naturaleza del riesgo. Cuando subir una versión y promoverla a producción son dos actos distintos, el despliegue deja de ser un salto irreversible y se convierte en una decisión con vuelta atrás: puedes construir sin publicar, publicar sin activar, activar para una fracción del tráfico y revertir en segundos volviendo a apuntar a la versión anterior. Esa separación, que en la práctica cuesta dos comandos en lugar de uno, es probablemente la mejora de fiabilidad más barata disponible en toda la cadena, y es la razón por la que merece la pena entender el despliegue como parte de la arquitectura y no como el trámite que viene después de ella.

⚔️ Reconstruye tu flujo de despliegue

Descompón el flujo de Pages de un proyecto real en sus cuatro funciones y comprueba cuáles cubriría hoy tu despliegue manual.
Configura Workers Builds con el comando de build de tu proyecto y verifica que una rama secundaria genera una URL de previsualización propia.
Escribe un flujo de GitHub Actions que ejecute tipos y pruebas antes de desplegar, y confirma que un fallo en las pruebas impide la publicación.
Crea un token de alcance limitado para ese flujo, enumera los permisos que le diste y justifica por qué cada uno es imprescindible.
Practica la separación entre subir y promover: publica una versión sin tráfico, revisa su URL, promuévela y después revierte a la anterior midiendo cuánto tardas.