Pipelines que piensan, infra que no rompe: Kiro headless mode en acción

Introducción

¿Cuántas veces mergeaste un cambio de infraestructura y te enteraste del problema en producción? ¿Cuántos security groups abiertos al mundo, cuántos IAM con * en Action, cuántos secrets hardcodeados llegaron a main porque nadie revisó el Terraform con suficiente detalle?

La revisión manual de infraestructura como código no escala. Los equipos crecen, los PRs se acumulan, y la presión por deployar rápido termina ganándole al rigor. Lo que necesitamos es que el pipeline piense por nosotros — y exactamente eso es lo que construimos en esta demo.

En este artículo te muestro cómo armé un flujo completo de revisión automática de IaC con Kiro headless mode, integrado directamente en GitHub Actions, que analiza cada PR de Terraform y postea un comentario con hallazgos de seguridad, calidad y buenas prácticas. Sin intervención humana, sin herramientas externas, sin configuración compleja.

¿Qué es Kiro headless mode?

Kiro CLI 2.0 introdujo el modo headless (sin interfaz gráfica), una forma de ejecutar kiro-cli de manera programática dentro de cualquier entorno automatizado.

La idea es simple: generás una API key en kiro.dev/settings/api, la agregás como variable de entorno, y Kiro CLI se ejecuta sin necesidad de que haya alguien sentado frente a una terminal.

Lo que lo hace poderoso:

Acceso completo a todos los agentes, herramientas y capacidades de una sesión interactiva.
Sin intervención humana: podés generar PRs, ejecutar reviews, troubleshootear o documentar sin que nadie esté monitoreando.
Multiplataforma: funciona nativamente en macOS, Linux y Windows.

Una línea para instalar:

curl -fsSL https://cli.kiro.dev/install | bash

La demo: review automático de Terraform en cada PR

El escenario

Tenemos un repositorio con infraestructura en Terraform para un servicio ECS Fargate en AWS. El archivo main.tf tiene bugs intencionales — security groups abiertos, IAM demasiado permisivo, CIDR blocks inválidos, secretos expuestos — diseñados para que Kiro los detecte.

El objetivo: que cada PR que toque terraform/ reciba automáticamente un comentario con un análisis profundo de seguridad, calidad e infraestructura, sin que nadie tenga que pedirlo.

Estructura del proyecto

Cómo funciona el workflow de review

El workflow kiro-review.yml es el corazón de la demo. Veamos cada parte:

1. Triggers

on:
  pull_request:
    paths:
      - 'terraform/**'
  workflow_dispatch:

Se dispara automáticamente en cada PR que modifique archivos en terraform/, o manualmente vía workflow_dispatch para reviews on-demand.

2. Concurrencia inteligente

concurrency:
  group: kiro-review-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

Si pusheás de nuevo al mismo PR, el run anterior se cancela automáticamente. Esto ahorra créditos de Kiro y evita comentarios duplicados.

3. Ejecución de Kiro CLI

El paso clave es la invocación de kiro-cli chat con el agente code-reviewer:

kiro-cli chat \
  --no-interactive \
  --agent code-reviewer \
  --trust-all-tools \
  "Realiza una revisión completa de seguridad, calidad y buenas prácticas
   de infraestructura sobre TODO el contenido del directorio terraform/..."

Los flags importantes:

Flag	Qué hace
`--no-interactive`	Modo headless, sin esperar input del usuario
`--agent code-reviewer`	Usa el agente especializado en review de código
`--trust-all-tools`	Permite al agente usar todas las herramientas disponibles

El prompt le pide a Kiro que:

Lea todos los archivos .tf, no solo los modificados.
Analice seguridad, IAM, secretos, red, cifrado, tags, costos y más.
Organice los hallazgos por severidad (Crítico / Alto / Medio / Bajo).
Incluya archivo afectado, líneas, impacto y fix accionable.
Genere un resumen ejecutivo y priorización.

4. Limpieza de salida

La salida cruda de kiro-cli incluye secuencias ANSI, spinners, logs internos y fences de código rotos. El script clean-kiro-output.js la transforma en Markdown limpio en 7 fases:

Fase	Descripción
1 — ANSI	Elimina secuencias de escape, spinners, box-drawing
2 — Content start	Detecta dónde empieza el contenido real
3 — Noise	Remueve logs de herramientas y meta-comentarios del agente
4 — Loose fences	Convierte marcadores de lenguaje sueltos en code fences
5 — Fence repair	Fusiona bloques HCL partidos, cierra fences huérfanos
6 — Cleanup	Normaliza saltos de línea, asegura paridad de fences
7 — Write	Escribe el resultado final

Cada fase está envuelta en try/catch individual — si una falla, las demás siguen ejecutándose.

5. Comentario en el PR

Usando actions/github-script, el workflow:

Lee el Markdown limpio.
Busca si ya existe un comentario previo del bot (## 🤖 Kiro Code Review).
Si existe, lo actualiza in-place. Si no, lo crea.

Esto elimina el spam de comentarios cuando iterás sobre el mismo PR.

Resultados en acción

Review completo en el PR

Esto es lo que Kiro genera automáticamente en cada PR:

Cada hallazgo incluye:

Título claro del problema.
Archivo y líneas afectadas.
Explicación de por qué es un problema.
Impacto real en la infraestructura.
Fix accionable con ejemplo de código corregido.

Resumen ejecutivo

Al final del review, Kiro genera un resumen con la severidad y cantidad de hallazgos, más una priorización recomendada:

Bonus: documentación automática con Kiro

Como extra, el repo incluye un segundo workflow (kiro-docs.yml) que demuestra otra capacidad de Kiro headless: generación automática de documentación.

Cómo funciona

Se dispara con cada push a master que modifique código fuente (ignora docs/, *.md y .github/).
Kiro escanea el repo completo con el agente doc-generator.
Actualiza docs/ y README.md según el estado real del código.
Si hay cambios, los pushea a una rama docs/auto-update-<timestamp>.

name: Kiro Documentation Generator

on:
  push:
    branches: [master]
    paths-ignore:
      - 'docs/**'
      - '*.md'
      - '.github/**'

El prompt instruye a Kiro para que:

Actualice documentación existente sin perder información útil.
Cree documentación para módulos no documentados.
Corrija documentación desactualizada.
Mantenga un estilo claro, ordenado y orientado a desarrolladores.

Esto muestra que Kiro no es solo para reviews — puede ser parte activa del mantenimiento de un proyecto, manteniendo la documentación al día como parte del flujo CI/CD.

Setup: cómo replicar esto en tu repo

Requisitos previos

Cuenta de GitHub con acceso a GitHub Actions.
API key de Kiro (kiro.dev/settings/api), requiere plan Pro, Pro+ o Power.

Paso a paso

1. Fork del repo

https://github.com/roxsross/kiro-iac-review.git

2. Configurar el secret

Settings → Secrets and variables → Actions → New repository secret
  Name: KIRO_API_KEY
  Value: <tu API key de Kiro>

3. Abrir un PR que toque Terraform

git checkout -b feat/test-review
# Hacé un cambio en terraform/main.tf
git add terraform/main.tf
git commit -m "feat(terraform): test kiro review"
git push -u origin feat/test-review
gh pr create --base master --fill

4. Esperar ~60 segundos

El comentario de Kiro aparece automáticamente en el PR.

Branch protection recomendada

Para que el review sea enforzable:

Settings → Branches → Add rule → master

✅ Require a pull request before merging
✅ Require status checks to pass → AI Code Review
✅ Require branches to be up to date before merging

Flujo de trabajo recomendado

Lecciones aprendidas

Lo que funcionó bien

El prompt es todo. La calidad del review depende directamente del prompt que le das a Kiro. Ser explícito sobre qué analizar, en qué formato reportar y qué priorizar hace una diferencia enorme.
La limpieza de salida es necesaria. La salida cruda de kiro-cli incluye ruido del CLI que rompe el Markdown en GitHub. El script de limpieza con 7 fases resilientes resuelve eso sin fragilidad.
Comment update > comment create. Actualizar el mismo comentario en vez de crear uno nuevo mantiene el PR limpio cuando iterás.
Concurrency ahorra créditos. cancel-in-progress es clave cuando el equipo pushea seguido al mismo PR.

Lo que hay que tener en cuenta

Créditos: cada run consume créditos de Kiro. Usá los triggers con paths específicos para evitar runs innecesarios.
Timeout: 15 minutos es suficiente para repos chicos. Para repos grandes, ajustá según necesidad.
El review no reemplaza al humano: Kiro encuentra problemas técnicos, pero las decisiones de arquitectura y trade-offs siguen siendo humanas.

Conclusión

Lo que construimos acá es simple en concepto pero poderoso en práctica: un pipeline que piensa antes de deployar. Kiro headless mode corre dentro de GitHub Actions, revisa cada PR de Terraform de forma automática, y postea un comentario estructurado con hallazgos accionables.

No reemplaza la revisión humana — la potencia. Te da un primer pase automatizado que atrapa los problemas obvios (y no tan obvios) antes de que lleguen a producción. Y como bonus, puede mantener tu documentación actualizada sin esfuerzo extra.

El código está disponible para que lo forkees, lo pruebes y lo adaptes: https://github.com/roxsross/kiro-iac-review.git

Referencias

🔥 Build with fire, deploy with power 🔥

@roxsross · roxs.dev