Prompts para Crear y Debuggear Pipelines de CI con IA

El pipeline empezó a fallar. Te llevas veinte minutos haciendo clic en la interfaz hasta encontrar la línea roja del log, otros veinte copiando ese trozo a un modelo, y otros veinte explicando el contexto de un proyecto que el modelo no ha visto nunca. Y luego resulta que era un : de más. Eso pasa casi todos los días en casi todos los repositorios.

GitHub Actions tiene mala fama con la IA, y no es del todo injusto: su superficie de error es enorme. Los errores más comunes no son de programación, son de orquestación. Un if: mal escrito, un secret que no existe en el entorno del pull request, una versión de Node que ya no compila con tu package.json. Son cosas que un modelo sí puede diagnosticar si le das el log correcto.

La diferencia es qué le pasas. Un log de 4.000 líneas no sirve. Cuarenta líneas con contexto sí. Eso es lo que vamos a ver aquí.

Si el deploy te importa más que el pipeline, empieza por deploy gratis con GitHub Actions, Netlify y Vercel, que tiene la parte de despliegue ya resuelta. Y si tu problema es que el repositorio está hecho un desastre antes de llegar al CI, echale un vistazo a los comandos de Git esenciales.

Cuatro cosas que conviene saber antes de preguntar nada

1. Pega el log del paso que falló, no el log entero. La salida de los 15 pasos que pasaron es ruido. Lo que importa empieza en la línea que dice Error:.

2. Da siempre las versiones. Node 20 y Node 24 se comportan distinto con ESM. Los runners cambian. Sin el dato, la IA apuesta por la versión más común y se equivoca.

3. Enseña el workflow entero cuando depures YAML. Un error de indentación en la línea 40 puede venir de las líneas 12 y 25. El fragmento no basta.

4. No le des permisos para escribir. Un workflow que se auto-modifica desde un paso que consume IA es una superficie de ataque. Que proponga, tú aplicas.

Los prompts

1. Crear un workflow desde cero

Necesito un workflow de GitHub Actions para este repositorio.

Contexto del repo:
- Lenguaje y runtime: [Node 22 / Python 3.13 / Go 1.24].
- Gestor de paquetes: [pnpm 10 / npm 11 / uv].
- Comando de instalación: [pnpm install --frozen-lockfile].
- Comando de test: [pnpm test].
- Comando de lint: [pnpm lint].
- Comando de build: [pnpm build].

Quiero que:
1. Se ejecute en pull requests contra [main] y en cada push a main.
2. Use el menor número de pasos posible. Nada de pasos decorativos.
3. Instale la versión exacta de runtime que tengo en .tool-versions,
   .nvmrc o mise.toml (te lo pego abajo si existe).
4. Faille rápido: si el lint falla, no sigas con los tests.

Aquí tienes los ficheros de configuración:
[pegar package.json o el equivalente]

Devuelve el YAML completo del workflow, con comentarios explicando
cada bloque no obvio. Usa versiones fijadas de las actions
(nunca @main, ni @v4 flotante sin fijar a SHA si puede ser).

Por qué funciona: el punto 2 es contra-intuitivo y es el que más importa. La mitad de los workflows que genera la IA (y la gente) tienen pasos redundantes porque el modelo copia estructura de tutoriales. Pedir el mínimo posible obliga a que cada run: justifique su existencia.

Ejemplo real de salida para un proyecto Node:

name: CI

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

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

El bloque concurrency es lo que más se olvida y lo que más duele: cancela el run anterior cuando metes otro push, así no pagas minutos por builds que nadie va a mirar.

2. La matriz de versiones

Quiero probar mi proyecto en varias versiones de runtime.

Requisito: que la matriz cubra [Node 20, 22 y 24] y que una versión
que falle NO cancele las otras dos (quiero ver todos los resultados
en un solo run).

Genera el job con estrategia matrix.

Detalles:
- Nombra cada job con la versión incluida, para que se lea fácil en la
  UI.
- Cache por versión: usa el caché nativo de setup-node con la clave
  correcta para que cada versión tenga su propia.
- Marca la versión principal (la de mi package.json engines) como
  `continue-on-error: false` y las experimentales como `true`, para
  que las nuevas no me rompan la rama mientras las integro.

Mi package.json engines: [pegar engines]

Por qué funciona: fail-fast: false es lo que evita que la primera versión que falle te oculte las demás. Y la combinación con continue-on-error por entrada te permite adoptar una versión nueva sin bloquear el repo el mismo día que la sacas.

Estrategia	Cuándo	Coste	Nota
Versión única	Repositorio estable, un solo runtime	1x	Lo más barato y lo más simple
Versiones fijas (matrix)	Compatibilidad con clientes	Nx	Necesita caché por versión
fail-fast: false	Cualquier matriz	Nx	Ves todos los fallos a la vez
max-parallel	Matrices grandes	Nx	Evita agotar los runners
continue-on-error por entrada	Adoptar versiones nuevas	Nx	No bloquea la rama por probarla
Fichero .nvmrc como fuente	Un solo sitio de verdad	1x	La CI no duplica el número
matrix desde package.json	Muchos runtimes	Nx	Un único origen de verdad

3. Cachear dependencias sin pagar más

Mi pipeline tarda [X] minutos y casi todo es `install`.
Gestor de paquetes: [pnpm/npm/yarn]. Lockfile: [nombre].
Fichero de configuración: [pegar el inicio de package.json].

Quiero cachear las dependencias y acelerar el pipeline.

Dime:
1. La opción nativa (`cache:` en setup-node) y si es la adecuada
   para mi caso.
2. La opción con actions/cache manual, con el YAML completo,
   incluyendo la clave con hash del lockfile.
3. Qué directorios exactos hay que cachear según mi gestor.
4. Cuánto espacio ocupa y en qué momento del pipeline se guarda la
   caché (ojo: solo si el job termina bien).
5. Qué pasa si el lockfile cambia: ¿se crea una caché nueva o nunca
   vuelve a guardar?

Abrevia el job tanto como sea posible sin romper nada.

Por qué funciona: setup-node con cache: pnpm resuelve el 80% de los casos en tres líneas, pero la clave es la que hace el trabajo. La parte final de la pregunta (qué pasa cuando cambia el lockfile) es la que evita el clásico problema de “caché que nunca se actualiza”.

Si quieres ver el impacto medido, en la guía de deploy con GitHub Actions tienes números de antes y después de cachear.

4. Debuggear un pipeline que falla

Este es el prompt que usas el martes por la mañana cuando nada funciona.

Mi workflow de GitHub Actions falla. Aquí tienes el contexto y el log.

Workflow (completo):
[pegar el YAML entero]

Log del job, desde la línea donde empieza el error:
[pegar solo el paso que falló, con las 5 líneas anteriores]

Repo:
- Runtime: [versión exacta]
- Sistema operativo del runner: [ubuntu-latest / ubuntu-24.04 / macos-14]
- Node: [versión]
- Sistema de archivos sensible a mayúsculas: [sí / no]

Método:
1. Identifica el error raíz, no el síntoma.
2. Cita la línea del log que lo demuestra. Si hay varias posibles,
   ordénalas por probabilidad.
3. Explica por qué ocurre, no solo qué es lo que dice el mensaje.
4. Dame el YAML corregido completo, no solo el fragmento.
5. Dime cómo verificar que está arreglado en local, antes de subirlo.

No propongas rodeos (quitar el flag, desactivar el check) salvo que
sea la única opción, y en ese caso explica qué estamos ocultando.

Por qué funciona: la instrucción de “error raíz, no síntoma” es la que mueve la IA del copypaste del mensaje de error al análisis de causa. Y el paso 5 (verificar en local) te ahorra el ciclo de push y esperar ocho minutos solo para descubrir que el fallo se reproduce en tu máquina.

Ejemplo real de salida:

Error raíz: el job falla en `pnpm install`, no en los tests.

El mensaje es "ERR_PNPM_LOCKFILE_BREAKING_CHANGE" (línea 184 del log).
Eso no es un problema de tu package.json: es que el lockfile está en
un formato incompatible con la versión de pnpm que usa el runner.

Se evidencia en que falla antes del primer "Packages: +1234".

Arreglo: fijar la versión de pnpm en el action de setup, con este
bloque en lugar del que tienes:

    - uses: pnpm/action-setup@v4
      with:
        version: 10.11.0   # fijar, no "latest"

Verificar en local: `corepack enable && rm -f pnpm-lock.yaml &&
pnpm install && git diff pnpm-lock.yaml`. Si el diff solo cambia la
cabecera de versión, ya está.

5. El paso que falla en local pero no en CI

Este código funciona en mi máquina y falla en GitHub Actions.

Local: [OS, versión, Node, gestor de paquetes, caso de uso].
CI: [runner, versión, Node, gestor de paquetes].

Log del fallo:
[pegar]

Diferencias que se me ocurren:
[listar las que sepas]

Causas más probables en este orden de frecuencia:
- Versión de Node distinta entre local y CI.
- Sensibilidad a mayúsculas y minúsculas: macOS y Windows no la
  tienen, Linux sí.
- Variables de entorno que tengo en local y no en CI.
- Zona horaria o configuración regional distintas.
- Lockfile desincronizado.

Para cada causa que consideres plausible: cómo la confirmo en dos
minutos. Dame comandos concretos.

Por qué funciona: la lista de diferencias que le das es el andamiaje. Sin ella, la IA enumera veinte causas genéricas. Con ella, verifica una a una y descarta en minutos en lugar de horas.

El clásico que más veces me ha pasado a mí es el de las mayúsculas y minúsculas en el import de un archivo. En local funciona, en Linux no, y el mensaje de error no dice nada útil.

6. Secrets y variables de entorno

Necesito manejar configuración sensible en mi workflow de GitHub
Actions. Tengo estos valores:

- [LISTAR VARIABLES Y SECRETOS, con sus NOMBRES, sin los valores]

Quiero:
1. Qué va como secret y qué va como variable normal, y por qué.
2. El bloque `env:` correcto para cada nivel (workflow, job, step).
3. Cómo paso un valor entre jobs sin exponerlo.
4. Cómo depurar sin imprimir el valor (solo si está definido y de
   qué longitud).
5. Los errores típicos con secrets: qué pasa si no está disponible en
   pull requests de forks, y cómo puedo testear el workflow sin
   esperar al merge.

Devuelve el YAML con `secrets.NAME` / `vars.NAME` bien puesto y un
comentario al lado de cada uno explicando por qué es secret o var.

Por qué funciona: la diferencia entre secrets y vars (visibles en PRs de forks, secretos no) es uno de los puntos donde más se falla al revisar los workflows sin querer, y es un detalle de la plataforma que la IA conoce bien si le preguntas directamente.

Ojo: los secrets no están disponibles en workflows que se disparan desde forks. Para probarlos, lo normal es ejecutar el workflow con workflow_dispatch manual o desde una rama del propio repositorio.

7. Acelerar el pipeline que ya funciona

Este es mi workflow actual:

[pegar YAML]

Tiempos reales por paso (del último run):
[pegar la tabla de duración de cada paso]

Objetivo: bajar de [X] a [Y] minutos sin romper nada.

Analiza:
1. Qué pasos se ejecutan en paralelo y podrían solaparse.
2. Qué pasos podrían cachearse o saltarse con `paths` en el trigger.
3. Qué pasos son redundantes porque otro ya valida lo mismo.
4. Cuánto se gana quitando cada uno. Ordénalo por impacto.
5. Qué pasa si cambio el trigger para que no se ejecute en cada push.

Y dame el YAML optimizado al final, con un comentario en cada cambio
explicando cuánto ahorra aproximadamente.

Por qué funciona: los tiempos reales son el dato que la IA no puede inventar. Dárselos y el análisis deja de ser genérico. El comentario con el ahorro estimado es lo que te permite después descartar cambios cuando el ganho no compensa.

Las tres palancas que más rinden casi siempre son las mismas: concurrency para cancelar runs viejos, caché de dependencias, y paths en el trigger para que la documentación no dispare la matriz de tests.

8. Deploy automático

Quiero desplegar automáticamente desde GitHub Actions.

Situación:
- Hosting: [Netlify / Vercel / Cloudflare Pages / servidor propio].
- Comando de build: [x]
- Directorio de salida: [dist]
- Entorno: [producción desde main, staging desde develop].

Requisito: que nadie pueda desplegar sin pasar por main. Nada de
deploy en cada push a feature branches.

Genera el workflow con:
1. El paso de build en el job.
2. El despliegue solo en push a main, o con aprobación manual
   (environment con required reviewers).
3. El manejo de secrets de la plataforma.
4. Qué pasa si el deploy falla: ¿se hace rollback? Explícame las
   opciones y elige una.
5. Deploys con previews para pull requests, si la plataforma lo
   permite.

Antes de escribir el YAML, dime si hay algún problema de seguridad
en el diseño que te describo.

Por qué funciona: la parte de “nadie despliega sin pasar por main” es la que se olvida. Un workflow con trigger en todas las ramas significa que cualquiera con acceso de escritura puede desplegar lo que sea, en cualquier momento. Y la última línea (revisar el diseño antes) hace que la IA te señale los riesgos de permisos antes de que los tengas.

El detalle de los deploys con preview para pull requests es lo que más acelera el ciclo de desarrollo, y la mayoría de plataformas lo tienen resuelto.

9. Los errores más comunes de GitHub Actions

Hazme una revisión preventiva de mi workflow buscando errores que
solo aparecen en CI, no en local.

[pegar el YAML]

Revisa punto por punto:
1. Sintaxis YAML y errores de indentación. Los quiero ver marcados.
2. Permisos: ¿el workflow concede permisos demasiado altos? ¿Hay acciones
   de terceros con permisos amplios?
3. Secrets y variables: nombres correctos y disponibilidad en PRs de
   forks.
4. Triggers: ¿se dispara más veces de lo necesario? ¿Falta un path?
5. Versiones: Node, Python, runtime. ¿Están fijadas o flotan?
6. Dependencias de red: ¿algo asume acceso a internet no
   garantizado?
7. Race conditions: dos jobs que escriben en el mismo sitio.
8. Coste: runners que podrían ser más baratos o jobs que no
   deberían ejecutarse siempre.
9. Acciones de terceros: ¿el owner/repo existe? ¿la versión existe?

Devuelve tabla: línea | problema | gravedad (bloqueante/alto/medio/bajo)
| arreglo concreto.

Por qué funciona: es una revisión estática del YAML, que es exactamente lo que un modelo hace bien. Y el formato de tabla con gravedad te permite ir de arriba abajo arreglando solo lo que importa, en lugar de reescribir el workflow entero.

Cinco de esos nueve puntos los tienes ya cubiertos con los prompts anteriores. Este es el que usas una vez al mes como revisión de seguridad y de coste.

10. Convertir el pipeline lento en una decisión informada

Mi pipeline tarda 12 minutos y bloquea el merge.
Equipo: [número de personas]. Frecuencia de push: [por día].

Salida del log con los tiempos por paso:
[pegar]

Analiza:
1. ¿El tiempo viene de esperar (red, installs) o de calcular
   (tests, build)?
2. Cuánto se ganaría con acciones más rápidas: tests en paralelo,
   matrix, shards, caching, runners más potentes.
3. Cuánto se ganaría con un job de solo-lint en pull requests y el
   suite completo solo en main.
4. ¿Vale la pena el aumento de gasto en minutos que eso implica?
   Con los números de arriba, no en abstracto.
5. La estrategia que recomendarías, con el trade-off explícito.

No me des una respuesta fácil: quiero el razonamiento para poder
decidir.

Por qué funciona: separa el tiempo de espera del de cómputo, que llevan a soluciones distintas. Y pedir el trade-off explícito evita la respuesta fácil (“usa una matriz más grande”) que siempre suena bien y casi nunca sale a cuenta en un repo pequeño.

Catálogo de prompts y para qué momento son

Momento	Prompt	Resultado esperado
Empezar un workflow	#1 Crear desde cero	YAML mínimo y funcional
Compatibilidad de runtimes	#2 Matriz	Varias versiones en un run
Instalaciones lentas	#3 Caché	Install de 40s a 5s
Build roto	#4 Debuggear pipeline	Causa raíz y YAML corregido
”Funciona en local”	#5 Diferencias local/CI	Causas ordenadas por probabilidad
Config sensible	#6 Secrets y env	Bloques env bien colocados
Pipeline de 15 minutos	#7 Acelerar	YAML optimizado con ahorro estimado
Despliegue	#8 Deploy automático	Trigger y gates correctos
Revisión periódica	#9 Errores comunes	Tabla de problemas por línea
Decidir inversión	#10 Slow pipeline	Trade-off con números reales

Anti-patrones

❌ El workflow inflado por steps decorativos

- name: Print repository info
  run: echo "This is the repository"
- name: Hello
  run: echo "Hello"
- name: Check if git is installed
  run: which git || echo "not found"

Cada step es un contenedor que arranca. Tres steps de relleno son varios segundos que pagas en cada run, durante meses.

✅ El mismo workflow con lo mínimo

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
- run: npm ci
- run: npm test

❌ El trigger que se dispara en todo

on:
  push:
    branches: ['**']      # cada push, cada rama
  pull_request:           # y cada PR
  schedule:
    - cron: '0 * * * *'   # y cada hora

Un cambio en README dispara la matriz de tests completa. Y si el schedule llega a ejecutarse sobre un repo grande, te quitas los minutos del mes sin darte cuenta.

✅ Trigger con filtros

on:
  pull_request:
    branches: [main]
    paths-ignore:
      - '**.md'
      - 'docs/**'
  push:
    branches: [main]

❌ Pedirle a la IA que “arregle” el workflow directamente

Arregla mi workflow de GitHub Actions y sube el cambio a main.

Un workflow con permisos de escritura que se auto-modifica a partir de contenido no confiable es exactamente el patrón que usan los ataques de supply chain. Que proponga el YAML, aplícalo tú.

✅ Que proponga el diff y lo revises tú

Dame el YAML corregido. No ejecutes nada ni hagas commit.
Lo aplico yo y lo reviso.

❌ Debuggear con el log completo

[4.000 líneas de log]
¿Qué falla?

La IA se distrae con la salida de los steps que pasaron y con el stack trace de algo que ya se resolvió en un paso posterior.

✅ Treinta líneas con contexto

Aquí está el paso que falló, las 5 líneas anteriores y el mensaje
de error: [pegar]
El workflow completo es: [pegar YAML]

❌ Permisos por defecto

permissions: write-all

Eso le da a cada action acceso de escritura en el repositorio, incluyendo las que instalas de terceros.

✅ Permisos mínimos por job

permissions:
  contents: read
  id-token: write   # solo si usas OIDC para cloud

Errores frecuentes

“La IA me da una solución y el pipeline sigue fallando”. Casi siempre es falta de versión. Node, Python, la versión del action, la versión del gestor de paquetes. Si el prompt 1 y el 4 no llevan las versiones exactas, la IA trabaja con supuestos.

“Se inventa un action que no existe”. Es raro pero pasa, sobre todo con acciones de comunidad poco conocidas. Comprueba con un grep rápido en GitHub antes de fiarte, y para acciones oficiales pide siempre la versión con tag explícito.

“El YAML que devuelve tiene un error de indentación”. Los modelos manejan mal la indentación cuando el bloque incluye expresiones ${{ }} con llaves. Pídele el fichero completo en un solo bloque y valida antes de commitear.

“Mi caché no se está usando”. Suele ser por dos motivos: la clave del lockfile cambió (y por tanto la clave de caché es nueva), o el job terminó con error y por diseño no guardó la caché. El paso 3 cubre los dos casos.

“Los minutos se me acaban sin saber por qué”. Ejecuta gh run list --limit 50 y mira la duración media. Si el 80% del gasto está en un solo workflow con matriz sobre push a feature branches, ahí tienes la respuesta. El prompt 10 te ayuda a decidir el arreglo con números.

“El workflow pasa en el PR y falla al mergear”. Suele ser una diferencia entre el evento pull_request y el evento push: los secrets del repositorio no están disponibles en PRs de forks, y las variables de workflow_dispatch no existen. Comprueba si tu lógica tiene una rama distinta para cada evento.

El flujo completo

  Pipeline roto
      │
      ▼
 ┌─────────────┐
 │  Prompt #4  │  log del paso fallido + YAML completo + versiones
 └──────┬──────┘
        │ causa raíz identificada
        ├──────────────► ¿tienes las versiones? ──► no ──► Prompt #1
        ▼
 ┌─────────────┐
 │ Aplicar fix │  (tú, no la IA)
 └──────┬──────┘
        │
        ▼
 ┌─────────────┐
 │  Prompt #5  │  ¿solo fallaba en CI? → causas de entorno
 └──────┬──────┘
        │
        ▼
   ¿Pasa el pipeline?
     │         │
    NO        SÍ
     │         │
     ▼         ▼
   Repetir   ┌─────────────┐
             │  Prompt #7  │  acelerar: caché + concurrency + paths
             └──────┬──────┘
                    │
                    ▼
             ┌─────────────┐
             │  Prompt #9  │  revisión preventiva periódica
             └──────┬──────┘
                    │
                    ▼
             ┌─────────────┐
             │  Prompt #8  │  deploy con gates
             └─────────────┘

La diferencia entre esto y buscar en Google el error es que el modelo conoce la plataforma, no solo tu error. GitHub Actions cambia su comportamiento entre versiones, y las respuestas de hace dos años ya no sirven. Con las versiones en el prompt, tienes en el contexto el estado real de la plataforma.

Para el otro lado del pipeline, el código que se ejecuta, están los prompts para entender código que no es tuyo. Y si el pipeline está en un proyecto que tú no has escrito, los mejores prompts para depurar código con IA son el complemento natural.

Si necesitas aislar el entorno antes de culpar al CI, mira Docker para developers: reproducir localmente el fallo del runner es el atajo más corto cuando ya has descartado versiones.

Y para no tener que escribir el prompt desde cero cada vez, la herramienta generadora de prompts te deja el esqueleto listo para adaptar.