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

**Por** [**@roxsross**](https://github.com/roxsross) · [roxs.dev](https://roxs.dev)

* * *

## 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](https://kiro.dev/blog/kiro-cli-2) 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](https://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**:
    
    ```bash
    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

![](https://cdn.hashnode.com/uploads/covers/620c453d7cf10d2765e28b6c/5bbf76a8-bf9c-43ab-bf04-840715c3405b.png align="center")

* * *

## Cómo funciona el workflow de review

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

### 1\. Triggers

```yaml
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

```yaml
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`:

```bash
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:

1.  Lee el Markdown limpio.
    
2.  Busca si ya existe un comentario previo del bot (`## 🤖 Kiro Code Review`).
    
3.  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:

![](https://cdn.hashnode.com/uploads/covers/620c453d7cf10d2765e28b6c/07a8be9b-fee5-42f7-8872-34d8809878b4.png align="center")

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:

![](https://cdn.hashnode.com/uploads/covers/620c453d7cf10d2765e28b6c/c8a24785-0433-44af-819e-b15b53c8cac4.png align="center")

* * *

## 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

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

```yaml
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](https://kiro.dev/settings/api)), requiere plan Pro, Pro+ o Power.
    

### Paso a paso

**1\. Fork del repo**

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

**2\. Configurar el secret**

```plaintext
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**

```bash
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:

```plaintext
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

![](https://cdn.hashnode.com/uploads/covers/620c453d7cf10d2765e28b6c/22248142-6870-4dc7-890b-4874140f35e9.svg align="center")

* * *

## Lecciones aprendidas

### Lo que funcionó bien

1.  **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.
    
2.  **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.
    
3.  **Comment update > comment create.** Actualizar el mismo comentario en vez de crear uno nuevo mantiene el PR limpio cuando iterás.
    
4.  **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

*   [Kiro CLI 2.0: headless mode, Windows y nueva UX](https://kiro.dev/blog/kiro-cli-2)
    
*   [Kiro headless mode — documentación](https://kiro.dev/docs/cli/headless)
    
*   [Ejemplo práctico de CLI headless](https://kiro.dev/blog/headless-mode-example)
    
*   [Kiro steering files](https://kiro.dev/docs/cli/steering)
    

* * *

🔥 *Build with fire, deploy with power* 🔥

[**@roxsross**](https://github.com/roxsross) · [roxs.dev](https://roxs.dev)