CI propio con GitHub Actions: el pipeline que publica

En cuanto un proyecto necesita que las pruebas decidan si algo se publica, que varios repositorios se coordinen o que una persona apruebe explícitamente el paso a producción, el CI propio recupera su sitio. GitHub Actions es la opción más común y el patrón es engañosamente simple: un workflow que instala dependencias y ejecuta wrangler deploy. Lo que separa ese ejemplo de tres líneas de un pipeline que puedes dejar corriendo sin vigilancia es todo lo demás: un token cuyo alcance no exceda lo necesario, una caché que acelere sin convertirse en un vector de entrada, y unas puertas que garanticen que ninguna rama sin revisar acabe atendiendo clientes. Esta lección trata precisamente de ese resto, porque el paso de despliegue es la parte fácil y también la única que casi todos los tutoriales cubren.

El token es el permiso más peligroso del repositorio

Un token capaz de desplegar Workers puede sustituir el código que atiende a tus usuarios. Guardado como secreto de repositorio, queda al alcance de cualquier workflow que corra en él, y por tanto de cualquiera que pueda modificar un workflow. Esa cadena de razonamiento es la que debe gobernar cómo lo creas.

Merece la pena hacer el ejercicio completo antes de crear nada: enumera qué necesita tocar el despliegue —el Worker, quizá una zona para las rutas, quizá un namespace de KV si el pipeline lo administra— y no concedas ni un permiso más. Cada permiso extra es una capacidad que un atacante hereda entera el día que el secreto salga del repositorio.

Se genera en el panel de Cloudflare, y la plantilla de edición de Workers es un punto de partida razonable siempre que después acotes los recursos: la cuenta concreta, y las zonas concretas si el Worker usa rutas sobre un dominio. Un token que abarca todas las cuentas de la organización porque era más rápido de crear es una decisión que se paga entera el día que se filtre. Junto a él necesitarás el identificador de cuenta, que no es secreto pero conviene guardar igualmente como variable para no incrustarlo.

Hay dos hábitos más que cuestan poco y evitan mucho. El primero es fijar permissions explícitamente en el workflow, porque el token propio de GitHub también se inyecta y por defecto puede tener más alcance del necesario. El segundo es anclar las acciones de terceros a un commit concreto en lugar de a una etiqueta móvil: una etiqueta puede reapuntarse, y una acción comprometida corre en el mismo job que tu secreto de despliegue.

Un token por entorno no es paranoia, es lo que hace que la separación que declaraste en el manifiesto sea real también en quién puede publicar. Si el mismo token despliega staging y producción, la única barrera entre ambos es el flag --env que alguien escriba en un archivo YAML, y los flags se editan en un pull request. Con tokens distintos, custodiados en environments distintos, un cambio en el workflow de staging no puede alcanzar producción ni por error ni a propósito.

El workflow que despliega de verdad

name: desplegar
on:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  publicar:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run test
      - run: npx wrangler deploy --env production
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}

Tres detalles merecen atención porque no son decorativos. El bloque concurrency con un grupo fijo impide que dos merges casi simultáneos publiquen a la vez y que gane el que termine último, que no tiene por qué ser el más reciente; con cancel-in-progress en falso, además, ningún despliegue se interrumpe a medias. La clave environment ata el job a un GitHub Environment, que es donde vivirá la aprobación manual y el secreto de producción. Y npm ci en lugar de npm install garantiza que se instala exactamente lo que fija el archivo de bloqueo, sin resoluciones nuevas: un pipeline que puede instalar una dependencia distinta a la que probaste no es reproducible.

Invocar Wrangler directamente con npx es perfectamente válido y tiene la virtud de que la versión que corre es la de tus dependencias. La acción oficial cloudflare/wrangler-action es la alternativa cómoda cuando quieres pasar secretos de runtime en el mismo paso o encadenar comandos, y hace por debajo lo mismo. Elige una y sé consistente; mezclar ambas en el mismo repositorio genera diferencias de versión difíciles de rastrear.

Falla pronto y falla barato. Antes del despliegue conviene ejecutar la comprobación de tipos y un wrangler deploy --dry-run, que empaqueta el Worker y valida la configuración sin publicar nada. Ese paso atrapa la clase entera de errores que de otro modo se descubren a mitad del despliegue —un binding mal escrito, un import que no resuelve en el runtime de Workers, un bundle que excede el tamaño permitido— y los convierte en un fallo del pipeline antes de tocar producción. Cuesta segundos y es la diferencia entre un pull request rojo y un despliegue a medias.

Cachear sin envenenar la caché

La instalación de dependencias domina la duración del pipeline y es lo primero que se cachea. La forma correcta es dejar que actions/setup-node lo haga por ti, porque calcula la clave a partir del hash del archivo de bloqueo y cachea el almacén del gestor de paquetes, no la carpeta de módulos instalados.

Conviene también recordar que la caché no es un almacén infinito ni permanente: las entradas caducan por desuso y el repositorio tiene un tamaño máximo, a partir del cual las más antiguas se expulsan. Una clave demasiado específica —que cambie con cada commit— llena ese espacio con entradas que nadie volverá a leer y acaba expulsando justo la que sí servía. La combinación correcta es una clave exacta derivada del archivo de bloqueo y una clave de respaldo más genérica para el caso en que ese archivo haya cambiado.

El último punto es el que se ignora. Las cachés de GitHub Actions se comparten por ramas siguiendo una jerarquía: una entrada creada en la rama principal es legible desde cualquier rama, y —lo relevante— una entrada creada en una rama cualquiera puede acabar siendo restaurada por otro job. Si tu workflow de pull request escribe en la caché con una clave que después restaura el workflow de producción, has creado un canal por el que un cambio no revisado puede inyectar contenido en el pipeline que publica. La regla es simple: los jobs que despliegan restauran cachés, no las escriben, o usan un espacio de claves separado del que tocan las ramas de trabajo.

flowchart TD
PR[pull request] --> T[tests y lint]
T --> UP[versions upload]
UP --> URL[url de vista previa en el comentario]
MG[merge a main] --> T2[tests]
T2 --> AP[aprobacion en environment production]
AP --> DP[wrangler deploy]
DP --> PROD[trafico real]
style URL fill:#89b4fa,color:#11111b
style AP fill:#fab387,color:#11111b
style PROD fill:#f38ba8,color:#11111b

Puertas: preview en el pull request, producción tras aprobación

El pipeline maduro no es uno sino dos, con permisos distintos. El de pull request valida y produce una vista previa; el de la rama principal publica. La asimetría se implementa con los comandos que ya conoces: wrangler versions upload en el primero, wrangler deploy en el segundo.

# En el workflow de pull request
- run: npx wrangler versions upload --env staging --tag pr-${{ github.event.number }}
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_STAGING_TOKEN }}

Etiquetar la versión con el número del pull request tiene una virtud concreta: la etiqueta viaja con el artefacto y aparece en wrangler versions list, de modo que cualquiera puede relacionar una versión con la discusión que la originó sin salir de la terminal. Publicar además la URL de vista previa como comentario cierra el círculo, porque quien revisa el código no tiene que buscar dónde probarlo.

Fíjate en que el token es otro. El workflow que corre sobre código no revisado nunca debería tener acceso a la credencial de producción, y la forma de garantizarlo no es la buena voluntad sino los GitHub Environments: el secreto de producción se declara en el environment production, y solo los jobs que lo referencian pueden leerlo. Si además ese environment exige revisores, el despliegue se detiene esperando una aprobación humana que queda registrada.

Los pull requests desde forks merecen una nota. Por defecto no reciben secretos, lo cual es exactamente lo que quieres, y significa que su workflow no podrá subir una versión. Resistir la tentación de arreglarlo con el disparador que sí expone secretos al código del fork es una de las decisiones de seguridad más importantes que tomarás en el repositorio: ese atajo entrega la ejecución de código con tus credenciales a cualquiera que abra un pull request.

Queda por decidir quién dispara producción. Publicar en cada merge a la rama principal es el flujo más sano cuando las pruebas son de fiar, porque mantiene pequeño el lote de cambios. Publicar desde una etiqueta o una release da control explícito sobre el momento y encaja mejor cuando hay coordinación con otros equipos. Lo que no funciona es el término medio ambiguo —un despliegue manual que a veces se hace y a veces no—, porque produce el peor estado posible: nadie sabe con certeza si lo que hay en la rama principal es lo que están ejecutando los usuarios.