Módulo 6: Promoción, rollback y entrega documentada

8. Proyecto final: entrega versionada y documentada

Descripción

Al terminar esta lección vas a haber producido, de punta a punta, el entregable que da nombre a la guía: cumbre-automations empaquetado exactamente como lo pide el mercado, "as version-controlled, documented JSON". Un repositorio de Git con el workflow order-triage exportado por CLI, normalizado y documentado con README de handoff; los tres entornos dev/staging/prod aislados por Docker Compose; una pasada de prueba en sandbox ejecutada a costo cero; un runbook de promoción y rollback; y el chequeo de CI que valida el JSON en cada commit. Es defendible en una entrevista y funciona como artefacto de portafolio: la prueba concreta de que no solo construyes workflows, sino que los versionas, pruebas, promueves y operas como un dueño del sistema.

Esto importa porque es la prueba de que los seis módulos encajan. Hasta ahora practicaste cada capacidad por separado —versionar, aislar entornos, probar, promover, revertir, validar—. El proyecto final las junta en un solo entregable, en el orden correcto, y te muestra que el todo es más que la suma: un sistema entregable no es "hacer las seis cosas", es hacerlas de forma que se sostengan entre sí. Y te deja un artefacto real, no un ejercicio que se descarta: un repositorio que puedes enseñar y defender el lunes en una entrevista.

Conexión con el módulo: esta lección no introduce conceptos nuevos; integra los seis módulos de la guía. Cada fase del proyecto es una capacidad que ya construiste, puesta en su lugar dentro del entregable completo. Las piezas nuevas de este módulo —el runbook de promoción (lección 2), el runbook de rollback (lección 5) y el chequeo de CI (lección 7)— se suman a lo que ya tenías de los Módulos 2 a 5. Al terminar, cierras la tercera y última fase visual de la guía —"promoción y entrega profesional"— y con ella, la guía entera. Presta atención a cómo el runbook y el CI convierten un repositorio "ordenado" en un sistema "operable": esa es la diferencia final entre constructor y dueño.

Un entregable es una promesa que otro puede verificar

Antes de las manos a la obra, una palabra sobre qué es este entregable y por qué se arma así.

En el proyecto del Módulo 3 armaste un repositorio que "otro desarrollador aprobaría". Este proyecto sube la apuesta: armas un sistema que otra persona puede operar sin ti. La diferencia no es de tamaño, es de naturaleza. Un repositorio ordenado demuestra que sabes organizar; un sistema con entornos, runbooks y CI demuestra que sabes operar. Lo primero te hace un buen constructor; lo segundo, un dueño del sistema. Y el mercado —ya lo viste, oferta por oferta— paga por el segundo.

Piénsalo como la diferencia entre una casa bonita y una casa con escrituras. La casa bonita se ve bien y funciona mientras tú vivas en ella y sepas dónde está la llave del agua. La casa con escrituras se puede transferir: viene con los planos, el manual de la caldera, el número del plomero y la lista de qué hacer si se inunda el sótano. Cualquiera puede tomarla y operarla, porque no depende del conocimiento que vive solo en tu cabeza. Tu cumbre-automations va a ser la casa con escrituras: no solo funciona, sino que viene con todo lo que otra persona necesita para operarla, mejorarla y recuperarla cuando algo falle.

Hay una recompensa concreta en armarlo con seriedad: al terminar, no vas a "saber sobre" entregar sistemas de automatización, vas a tenerlo hecho. Y esa distancia —entre saber sobre y haber hecho— es enorme en una entrevista. Cualquiera puede describir un runbook de rollback; muy pocos pueden abrir el suyo, mostrar que lo ensayaron en staging, y explicar por qué el paso 5 re-importa a la instancia y no solo arregla el repo. Este proyecto te pone del segundo lado.

Una nota sobre el punto de partida. El proyecto asume que ya construiste, a lo largo de la guía, las piezas de los Módulos 2 a 5: el repositorio versionado, los tres entornos, la pasada de sandbox. Si vienes siguiendo el caso de Cumbre, ya las tienes. Si no tienes una instancia a mano, lee el proyecto completo de todos modos: la secuencia y su lógica se entienden igual, y las corres cuando tengas el entorno. Lo que se transfiere —el orden, el criterio de cada decisión— vale más que teclear los comandos una vez.

Ejemplo trabajado: el entregable completo, fase por fase

Vamos a ensamblar cumbre-automations en nueve fases. Cada fase abre con dónde estás y cierra con qué esperar, para que en todo momento sepas si vas bien. Las primeras tres fases confirman lo que ya construiste; las fases 4 a 8 agregan las piezas de este módulo; la 9 verifica y entrega.

Fase 0 — Dónde estás: seis módulos de trabajo

Punto de partida: todo lo que construiste en la guía, repartido en piezas. Este es el inventario que vas a integrar:

PiezaDe qué móduloEstado al empezar
Repositorio cumbre-automations versionado, con .gitignore y .gitattributesMódulos 2–3Listo
order-triage.json exportado por CLI, normalizado, con export.shMódulos 2–3Listo
docs/order-triage.md de handoff, credentials/README.mdMódulo 3Listo
Tres entornos dev/staging/prod por Docker Compose, cada uno con su N8N_ENCRYPTION_KEY y credenciales por entornoMódulo 4Listo
Una pasada de prueba en sandbox ejecutada a costo ceroMódulo 5Listo
Runbook de promoción, runbook de rollback, chequeo de CIMódulo 6Por agregar

Párate en el repositorio:

cd cumbre-automations

Qué esperar: git status te muestra un repositorio ya poblado con el trabajo de los Módulos 2 a 5. No partes de cero: partes de un repositorio ordenado al que le faltan las tres piezas de operación de este módulo. El proyecto es ensamblar el sistema completo, no construirlo desde el inicio.

Fase 1 — Confirmar la base versionada (Módulos 2–3)

Dónde estás: repositorio poblado, a punto de verificar sus cimientos. Antes de agregar nada, confirma que la base está sólida, porque todo lo demás se apoya en ella. Recorre esta lista rápida:

# El workflow existe, normalizado y con nombre legible:
ls workflows/order-triage.json

# Los secretos están blindados (el .gitignore cubre .env y credenciales):
cat .gitignore

# El script de exportación existe y es ejecutable:
ls -l scripts/export.sh

Qué esperar: order-triage.json está presente y, al abrirlo, se ve normalizado —sin pinData, versionId, meta.instanceId, con las claves ordenadas—. El .gitignore cubre .env, las exportaciones de credenciales y .n8n/. El export.sh está y es ejecutable. Si algo falla aquí, vuelve al Módulo 3 a completarlo antes de seguir: no tiene sentido montar la operación sobre una base incompleta.

Fase 2 — Confirmar los tres entornos (Módulo 4)

Dónde estás: base versionada confirmada. Ahora verifica que los tres entornos existen y están aislados, porque la promoción y el rollback de este módulo se mueven entre ellos. Tu repositorio debería tener la configuración por entorno que montaste en el Módulo 4 —un docker-compose por entorno, cada uno con su archivo de variables y su N8N_ENCRYPTION_KEY, y credenciales de prueba en dev/staging y reales en prod—.

Usa el layout que dejaste en el Módulo 4. Una forma representativa de organizarlo es una carpeta por entorno:

environments/
├── dev/       (docker-compose.yml + .env.example)
├── staging/   (docker-compose.yml + .env.example)
└── prod/      (docker-compose.yml + .env.example)

Lo que importa no es el nombre exacto de la carpeta, sino que se cumplan tres cosas del Módulo 4: cada entorno es una instancia aislada, cada uno tiene su propia N8N_ENCRYPTION_KEY, y los .env con valores reales no están en el repositorio (solo los .env.example sin valores, gracias al .gitignore de la fase 1).

Qué esperar: los tres entornos están definidos, aislados, y ninguno filtra secretos al repositorio. Confirma que un git status no muestra ningún .env con valores reales. Si levantas los tres, cada uno corre su propia instancia de n8n en su propio contenedor —n8n-dev, n8n-staging, n8n-prod—, que son los destinos entre los que promueves.

Fase 3 — Confirmar la pasada de sandbox (Módulo 5)

Dónde estás: entornos confirmados. Antes de documentar la promoción, confirma que existe la evidencia de que order-triage se probó en sandbox a costo cero, porque promover algo no probado rompe el principio del ascenso. La pasada del Módulo 5 usó datos sintéticos, llaves sandbox, dry run, replay de ejecución y aserciones con el nodo Evaluation, con modelos locales de Ollama para probar el nodo AI Agent sin gastar.

Deja constancia de esa pasada en el repositorio, en docs/sandbox-test-pass.md, para que el entregable muestre que se probó y cómo:

# Pasada de prueba en sandbox — order-triage

Ejecutada en el entorno staging, a costo cero.

## Qué se probó
- Clasificación de pedidos por el nodo AI Agent (modelo local de Ollama, sin costo de API).
- Enriquecimiento del pedido con el nodo HTTP Request contra el CRM sandbox.

## Cómo se probó (Módulo 5)
- Datos sintéticos: pedidos generados, sin datos de clientes reales.
- Llaves sandbox: el CRM de prueba, no el real.
- Dry run: los efectos secundarios (escritura al CRM) protegidos durante la prueba.
- Replay de ejecución: se re-ejecutaron ejecuciones fijadas para validar cambios.
- Aserciones con el nodo Evaluation: se verificó que la clasificación cae en las
  categorías esperadas (aprobado / revisión manual / falta información).

## Resultado
La pasada quedó verde antes de promover a prod. (Es un ejemplo de práctica; en un
proyecto real, adjunta las métricas y capturas de tus ejecuciones.)

Qué esperar: docs/sandbox-test-pass.md documenta que order-triage pasó su prueba en sandbox antes de cualquier promoción a prod. Esto no solo es evidencia para el portafolio; es la precondición honesta de la promoción: solo se promueve lo probado.

Fase 4 — El runbook de promoción (lección 2)

Dónde estás: base, entornos y prueba confirmados. Ahora agregas la primera pieza de operación de este módulo: el runbook que documenta cómo se promueve order-triage a prod. Va en docs/runbook-promotion.md:

# Runbook: promover order-triage a prod

## Cuándo usar esto
Cuando un cambio de order-triage pasó su prueba en sandbox (staging) y hay que
llevarlo a producción de forma controlada.

## Responsable
El operador con acceso al repositorio y al contenedor n8n-prod.

## Precondiciones
- El cambio está commiteado y revisado (diff aprobado en un pull request).
- La pasada de sandbox en staging quedó verde.
- Las credenciales reales (Cumbre CRM key, Cumbre LLM key) ya existen en prod.

## Pasos
1. Párate en el repositorio y confirma la versión a promover:
       cd cumbre-automations
       git diff HEAD~1 workflows/order-triage.json   # revisa que cambió SOLO lo esperado

2. Copia el JSON bueno al contenedor de prod:
       docker cp workflows/order-triage.json n8n-prod:/tmp/order-triage.json

3. Importa en prod (llega INACTIVO por defecto — es lo que queremos):
       docker exec -u node -it n8n-prod n8n import:workflow \
         --input=/tmp/order-triage.json

4. Abre order-triage en el editor de prod. Verifica que la lógica es la nueva y
   que los nodos con credencial (AI Agent, HTTP Request) resuelven, no en rojo.

5. Activa order-triage en prod (interruptor de activación), mirando.

## Verificación
- Un pedido real entra y se clasifica correctamente con la lógica nueva.
- El nodo del CRM autentica y responde sin error.

## Si algo sale mal
- Ejecuta docs/runbook-rollback.md de inmediato. No depures en prod.

Fíjate en cómo el runbook condensa toda la lección 2 en pasos ejecutables: sacar del repo, revisar el diff, importar inactivo, verificar credenciales, activar con intención. Y en cómo termina apuntando al runbook de rollback: la promoción y la reversión son dos caras del mismo procedimiento.

Qué esperar: docs/runbook-promotion.md existe y cualquier persona con los accesos podría promover order-triage a prod siguiéndolo, sin haber diseñado el sistema. Ese es el estándar: un runbook que otro puede ejecutar.

Fase 5 — El runbook de rollback, y ensayarlo (lección 5)

Dónde estás: el runbook de promoción listo. Ahora la salida de emergencia: el runbook de rollback de la lección 5, en docs/runbook-rollback.md (usa el que escribiste ahí, con sus dos mitades —revertir en el repo y re-importar a la instancia— y su verificación observable).

Pero agregar el archivo no basta: ensáyalo en staging, como aprendiste. Promueve a propósito una versión "mala" de order-triage a staging, y después ejecuta el runbook de rollback al pie de la letra para volver atrás. Deja constancia del ensayo al final del runbook:

## Ensayo (obligatorio antes de confiar en este runbook)
Ensayado en staging el <fecha>: se promovió a propósito una versión con el umbral
en 100, se ejecutó este runbook paso a paso, y staging volvió a la versión buena
en ~5 minutos. Ningún paso falló. (Repite el ensayo si cambias el procedimiento.)

Qué esperar: docs/runbook-rollback.md existe y fue ensayado en staging. La diferencia entre un runbook escrito y uno ensayado es la diferencia entre un plan y un deseo; tu entregable tiene la versión ensayada, con la fecha del simulacro. En una entrevista, "lo ensayé el martes en staging" pesa mucho más que "tengo un runbook".

Fase 6 — El chequeo de CI (lección 7)

Dónde estás: los dos runbooks listos. Ahora el inspector automático: el workflow de CI de la lección 7, en .github/workflows/validate-workflows.yml. Créalo con el contenido de esa lección —el que valida que cada workflow sea JSON parseable (jq empty) y esté normalizado (comparando con la forma que deja export.sh)—.

Recuerda el requisito estricto de la ruta: el archivo tiene que estar exactamente en .github/workflows/, con el punto inicial, o GitHub Actions no lo corre.

Qué esperar: al hacer push del archivo a GitHub, en la pestaña "Actions" aparece el workflow validate-workflows, y en cada commit que toque workflows/*.json corre solo, dejando una palomita verde si el JSON es válido y normalizado, o una equis roja con un mensaje útil si no. Prueba a propósito: commitea un order-triage.json con una coma de más y confirma que el chequeo se pone rojo; después arréglalo y confirma que vuelve a verde. Ver el detector de humo sonar y callar te confirma que funciona.

Fase 7 — Documentar cómo se construye con IA (lección 4)

Dónde estás: la operación automatizada. Agrega una nota corta que documente el lazo seguro de construcción con IA, porque es parte de cómo se opera este sistema y una pregunta de entrevista garantizada. Va en docs/ai-authoring.md:

# Construcción con IA — cómo y dónde

## Principio
La IA (vía el servidor MCP de n8n) construye y edita workflows SOLO en dev,
nunca en prod. En prod el módulo MCP está deshabilitado por configuración.

## Configuración por entorno
- dev:  N8N_MCP_ACCESS_ENABLED=true      (la IA puede construir aquí)
- prod: N8N_DISABLED_MODULES=mcp         (el endpoint MCP ni existe aquí)

## El lazo seguro
La IA propone en dev -> se exporta y commitea -> el humano revisa el DIFF en un
pull request -> se promueve por el flujo normal (dev -> staging -> prod).
La IA propone; el humano aprueba. Nunca se promueve lo que la IA dice, sino lo
que el diff revisado muestra.

(Verifica los nombres de variable y el endpoint MCP en la doc de tu versión de
n8n: esta área evoluciona rápido.)

Qué esperar: docs/ai-authoring.md deja por escrito el candado por entorno y el lazo seguro. Aunque no uses IA en cada cambio, documentarlo demuestra que sabes usarla sin perder el control —justo lo que un evaluador quiere confirmar—.

Fase 8 — El README de handoff que ata todo, más la evidencia visual

Dónde estás: todas las piezas en su lugar. Ahora el README.md de raíz, que es la portada del repositorio y lo primero que ve quien lo abre —un evaluador, un compañero, tú en seis meses—. Tiene que permitir arrancar y operar el sistema sin preguntarte nada. Agrégale, arriba, una captura de order-triage abierto en el editor de n8n, con su Webhook, su nodo AI Agent y su nodo HTTP Request conectados: la evidencia visual que vuelve tangible el JSON.

# cumbre-automations

![order-triage en el editor de n8n](docs/img/order-triage.png)

Automatizaciones de Cumbre, entregadas como version-controlled, documented JSON.

## Qué es esto
El repositorio de automatización de Cumbre. Contiene order-triage (Webhook ->
AI Agent -> HTTP Request al CRM), versionado, probado, con entornos y runbooks.

## Cómo arrancar (dev)
1. Copia environments/dev/.env.example a .env y rellena tus valores.
2. Levanta el entorno: docker compose -f environments/dev/docker-compose.yml up -d
3. Importa el workflow: ver docs/runbook-promotion.md.

## Cómo se opera
| Necesito… | Ver |
|---|---|
| Promover un cambio a prod | docs/runbook-promotion.md |
| Revertir un cambio que rompió prod | docs/runbook-rollback.md |
| Entender qué hace order-triage | docs/order-triage.md |
| Saber qué se probó y cómo | docs/sandbox-test-pass.md |
| Construir workflows con IA | docs/ai-authoring.md |
| Mantener el repo al día | scripts/export.sh |

## Dónde están los secretos
Fuera del repositorio, siempre. Cada entorno tiene sus credenciales en su
instancia; el repo solo lleva referencias. Ver credentials/README.md.

## Verificación automática
Cada commit que toca un workflow pasa por el chequeo de CI
(.github/workflows/validate-workflows.yml): JSON parseable y normalizado.

Fíjate en que el README no explica cada pieza en detalle —para eso están los docs—; orienta. Es un índice que manda a cada lugar según lo que la persona necesite hacer. Ese es el gesto del handoff: no volcar todo tu conocimiento, sino dejar el mapa para encontrarlo.

Qué esperar: un README.md de raíz con la captura arriba y la tabla de "cómo se opera" que apunta a cada runbook y doc. Un desconocido que abra el repositorio ve, en la portada, qué es el sistema, cómo arrancarlo y a dónde ir para cada operación. La casa con escrituras.

Fase 9 — Verificación final, seguridad, y entrega

Dónde estás: el entregable completo. Antes de commitear la entrega final, la revisión de seguridad, con el mismo rigor del Módulo 3:

git status

Revisa con ojo de auditor. Deben aparecer las piezas nuevas: docs/runbook-promotion.md, docs/runbook-rollback.md, docs/sandbox-test-pass.md, docs/ai-authoring.md, .github/workflows/validate-workflows.yml, el README.md actualizado, la imagen. No debe aparecer, bajo ninguna circunstancia: ningún .env con valores, ninguna exportación de credenciales, la carpeta .n8n/, ni nada con forma de secreto. Como doble chequeo, revisa el contenido antes de commitear:

git diff --cached

Lee buscando sk-, Bearer , password, llaves largas. Si encuentras un secreto, detente, sácalo, y si llegó a exportarse, rota esa credencial.

Cuando la verificación pasa, tú —no el script, no la IA— decides qué entra a la historia:

git add .
git commit -m "Entrega final: order-triage versionado, con entornos, pruebas, runbooks y CI"
git push

Qué esperar: un commit que captura el entregable completo, y —si tienes el remoto en GitHub— el push que lo hace visible y dispara el chequeo de CI por primera vez sobre la entrega. Abre tu repositorio en GitHub: ves la portada con la captura, la marca verde del CI, y toda la estructura navegable. cumbre-automations es, ahora, un artefacto de portafolio real y defendible.

La rúbrica de entrega: cómo se juzga un dueño del sistema

El estándar no es "hice las nueve fases"; es "un evaluador competente confirmaría que aquí hay un dueño del sistema, no solo un constructor". Esta es la lista con la que se juzga el entregable completo, agrupada por lo que demuestra cada capa:

Versionado y limpieza (Módulos 2–3):

  • order-triage.json exportado por CLI, normalizado (sin campos volátiles, claves ordenadas).
  • Un guardado sin cambios de lógica produciría un diff vacío tras normalizar.
  • El export.sh reproduce el estado del repo de un comando.

Seguridad (Módulo 3) — lo que se revisa primero y con más severidad:

  • Ningún valor de credencial en el repo, ni cifrado ni en claro, ni en la historia.
  • .gitignore cubre .env, exportaciones de credenciales y .n8n/.
  • Los secretos viven en cada instancia, no en el repositorio.

Entornos (Módulo 4):

  • Tres entornos aislados por Docker Compose, cada uno con su N8N_ENCRYPTION_KEY.
  • Credenciales de prueba en dev/staging, reales en prod, con la referencia resolviendo en cada uno.

Prueba (Módulo 5):

  • Evidencia de una pasada de sandbox ejecutada a costo cero, con lo que se probó y cómo.

Operación (Módulo 6) — lo que separa al dueño del constructor:

  • Runbook de promoción ejecutable por otra persona.
  • Runbook de rollback ejecutable y ensayado en staging, con las dos mitades (repo e instancia).
  • Chequeo de CI en verde que valida el JSON en cada commit.
  • Documentado el lazo seguro de construcción con IA (IA en dev, nunca en prod).

Handoff (todo junto):

  • README de raíz con evidencia visual que permite arrancar y operar sin preguntar al autor.
  • La prueba del desconocido pasa: alguien podría operar el sistema solo con la documentación.

Si tu cumbre-automations marca todas estas casillas, no es un ejercicio: es la prueba, verificable línea por línea, de que cruzaste de constructor de workflows a dueño del sistema de automatización. La capa que más gente falla es la de operación —los runbooks ensayados y el CI—, porque es la que este módulo agregó y la que menos gente sabe que el mercado pide. Es, no por casualidad, la que más te diferencia.

La defensa final: tu artefacto en la entrevista

Cierra el proyecto imaginando la conversación para la que lo construiste. Un entrevistador abre tu cumbre-automations y hace las preguntas que ya sabes responder, porque cada una es una decisión de diseño que puedes señalar con el dedo:

  • "¿Cómo llevas un cambio a producción?" → El runbook de promoción.
  • "¿Y si rompe algo?" → El runbook de rollback, ensayado en staging.
  • "¿Cómo garantizas que el JSON está bien?" → El CI en verde, que valida cada commit.
  • "¿Cómo pruebas sin tocar el CRM real?" → La pasada de sandbox a costo cero, con datos sintéticos y modelos locales.
  • "¿Cómo evitas filtrar una credencial?" → El .gitignore desde el primer commit y las credenciales fuera del repo.
  • "Si usas IA, ¿cómo no rompe producción?" → El lazo seguro: la IA en dev, el humano revisa el diff, se promueve.
  • "¿Podría otro tomar esto sin ti?" → El README de handoff, en vivo.

Ninguna de esas respuestas es teoría. Todas son evidencia que el entrevistador puede verificar abriendo tu repositorio. Esa es la diferencia entre decir "sé usar n8n" y demostrar "soy dueño de un sistema de automatización" —y es, palabra por palabra, lo que las mejores ofertas piden cuando escriben "as version-controlled, documented JSON" y "no prototype = no conversation"—.

Guarda este repositorio. Púlelo. Es el proyecto que vas a mostrar, y cada módulo de esta guía le agregó una capa que responde otra pregunta de entrevista.

Errores comunes

Entregar el repositorio ordenado pero sin la capa de operación (conceptual, el error que define este proyecto). Qué pasa: alguien arma un repositorio impecable —versionado, normalizado, documentado— pero se detiene ahí, sin runbooks ni CI, y cree que ya entregó "como profesional". En la entrevista, cuando le preguntan cómo promueve o revierte, no tiene qué señalar. Por qué pasa: la capa de operación es la más nueva y la que menos gente sabe que el mercado pide; es fácil creer que "ordenado" es suficiente. Cómo detectarlo: si tu repo no tiene runbooks ejecutables ni chequeo de CI, te falta justo lo que separa al dueño del constructor. Cómo corregirlo: un repositorio ordenado demuestra que organizas; los runbooks y el CI demuestran que operas. El entregable completo necesita las dos capas. La casa bonita no es la casa con escrituras.

Documentar un runbook sin ensayarlo (práctico). Qué pasa: alguien escribe los dos runbooks prolijos y los commitea, pero nunca los ejecuta. En una entrevista dice "tengo un runbook de rollback", y si el entrevistador pregunta "¿lo probaste?", la respuesta honesta es "no". Un runbook no ensayado casi siempre tiene un error que solo el ensayo revela. Por qué pasa: escribir se siente como terminar; ensayar parece opcional. Cómo detectarlo: si ningún runbook corrió de principio a fin, son hipótesis, no planes. Cómo corregirlo: ensaya el rollback en staging y deja constancia con la fecha. "Lo ensayé el martes" es una respuesta de dueño; "lo tengo escrito" es una de constructor. El ensayo es lo que convierte el documento en una garantía.

Olvidar la evidencia visual y entregar solo JSON (práctico, de portafolio). Qué pasa: alguien comparte un repositorio de puro JSON y espera que el evaluador "vea" el workflow. Quien no lee JSON con fluidez no logra imaginarlo, y el trabajo real no se comunica. Por qué pasa: para quien lo hizo, el JSON es el workflow; para quien lo evalúa desde afuera, es texto abstracto. Cómo detectarlo: si tu README no tiene una captura del order-triage armado, le falta la mitad tangible. Cómo corregirlo: pon la captura arriba en el README de raíz. La imagen muestra que funciona; el repo muestra que sabes entregarlo; juntos cuentan la historia completa. Un artefacto de portafolio se comunica en un vistazo o no se comunica.

Commitear la entrega final sin la verificación de seguridad (práctico). Qué pasa: alguien, con el entusiasmo de terminar, salta del último README directo a git add . && git commit && git push, sin el git status y git diff --cached de auditoría, y se lleva un .env o una exportación de credenciales a la historia —y peor, al remoto público de GitHub—. Por qué pasa: la verificación se siente como un trámite cuando ya "está todo listo". Cómo detectarlo: si empujaste sin haber mirado explícitamente qué estabas empujando, te saltaste el control. Cómo corregirlo: la verificación de seguridad no es opcional, y menos en la entrega final, que además va a un remoto visible. Mira siempre qué entra antes de que entre; en un push a GitHub, un secreto commiteado es un secreto publicado. Es más barato revisar que rotar credenciales y limpiar la historia después.

Ejercicios

Ejercicio 1 — Autoevalúa con la rúbrica completa. Toma tu cumbre-automations terminado (o el que armaste siguiendo el proyecto) y recórrelo con la rúbrica de entrega, casilla por casilla, prestando atención especial a la capa de operación. Anota cuáles marcas con confianza y cuáles no. Para cada casilla que no puedas marcar, escribe en una frase la acción concreta que falta.

Ver solución

No hay una respuesta única; el resultado es tu diagnóstico. Lo que la mayoría descubre es que las capas de versionado, seguridad y entornos se marcan con confianza —son las que más practicaron—, y que las que quedan flojas están en la capa de operación: el runbook de rollback ensayado (no solo escrito) y el CI en verde. También suele fallar la casilla de la historia limpia de secretos, porque se revisa el estado actual y no la historia.

Si una casilla no la puedes marcar, ahí está tu siguiente tarea, concreta y pequeña: no "mejora el repo" en abstracto, sino "ensaya el rollback en staging y anota la fecha" o "confirma que el CI corre en la pestaña Actions". La rúbrica convierte "¿está bien mi entregable?" en una lista de acciones puntuales.

Por qué funciona: revisarte con la rúbrica de un evaluador antes de que te revise uno de verdad es la habilidad que toda la guía persigue. Cada casilla que arreglas tú es un comentario que no te van a hacer en la entrevista. Y prestar atención a la capa de operación es prestar atención justo a lo que te diferencia.

Ejercicio 2 — Traza cada pieza a su módulo. Sin volver a mirar la fase 0, toma las siete piezas del entregable —repositorio versionado, order-triage normalizado, tres entornos, pasada de sandbox, runbook de promoción, runbook de rollback, chequeo de CI— y di de qué módulo de la guía viene cada una. Después explica en una frase por qué el orden de las fases del proyecto (confirmar la base, luego los entornos, luego la prueba, luego la operación) no es arbitrario.

Ver solución

Las piezas y sus módulos: repositorio versionado y order-triage normalizado → Módulos 2–3; tres entornos aislados → Módulo 4; pasada de sandbox → Módulo 5; runbook de promoción, runbook de rollback y chequeo de CI → Módulo 6 (lecciones 2, 5 y 7).

Por qué el orden no es arbitrario: cada fase se apoya en la anterior. No puedes documentar la promoción (fase 4) sin tener los entornos entre los que promueves (fase 2, Módulo 4); no puedes promover con honestidad sin la prueba que lo autoriza (fase 3, Módulo 5); no puedes revertir (fase 5) sin la base versionada a la que volver (fase 1, Módulos 2–3). El proyecto confirma los cimientos antes de montar la operación encima, porque la operación sin cimientos se derrumba. El orden es causal, no cronológico por casualidad.

Por qué funciona: ver que cada pieza del entregable viene de un módulo distinto te muestra que la guía entera fue construyendo, sin que lo notaras, las partes de un solo sistema. El proyecto final no agrega mucho contenido nuevo; revela que todo lo anterior era, desde el principio, un solo entregable desarmado en seis módulos.

Ejercicio 3 — Defiende tu artefacto. Elige tres de las siete preguntas de entrevista de la sección "La defensa final" y escribe, para cada una, la respuesta que darías señalando una pieza concreta de tu repositorio (no de Cumbre en abstracto). Practícalas en voz alta como si estuvieras en la entrevista.

Ver solución

No hay una respuesta única, porque señalas tu propio repositorio. Un ejemplo de tres:

  • "¿Y si un cambio rompe producción?" → "Tengo un runbook de rollback, aquí en docs/runbook-rollback.md, y lo ensayé en staging el martes: provoqué un problema a propósito y volví a la versión buena en unos cinco minutos. Tiene las dos mitades, revertir en el repo y re-importar a la instancia, porque arreglar solo el repo deja producción rota."
  • "¿Cómo garantizas que el JSON está bien?" → "Este chequeo de CI, en la pestaña Actions, valida cada commit: que el JSON sea parseable y esté normalizado. Miren, está en verde. Si commiteo algo roto, se pone rojo y me dice cómo arreglarlo, así la calidad no depende de que yo me acuerde de revisar."
  • "Si usas IA para construir, ¿cómo no rompe producción?" → "La IA solo construye en dev, vía MCP; en prod deshabilité el módulo MCP con N8N_DISABLED_MODULES=mcp, así que ni se puede conectar ahí. Lo que la IA propone pasa por un diff que reviso yo en un pull request antes de promoverse. La IA propone; yo apruebo."

Por qué funciona: practicar la defensa en voz alta, señalando piezas reales, es lo que convierte un buen repositorio en una buena entrevista. El artefacto no habla solo; tú lo defiendes. Y como cada respuesta apunta a evidencia verificable, no estás afirmando que sabes: lo estás demostrando. Esa es la diferencia que la guía entera te preparó para hacer.

Resumen y cierre de la guía

Llegaste al final. En esta lección integraste los seis módulos en un solo entregable: cumbre-automations, la casa con escrituras. Ensamblaste, en nueve fases, el repositorio versionado y normalizado (Módulos 2–3), los tres entornos aislados por Docker Compose (Módulo 4), la evidencia de la pasada de sandbox a costo cero (Módulo 5), y las tres piezas de operación de este módulo —el runbook de promoción, el runbook de rollback ensayado en staging, y el chequeo de CI en verde—, más la nota del lazo seguro de construcción con IA y un README de handoff con evidencia visual que permite operar el sistema sin ti. Lo verificaste con la rúbrica del dueño del sistema y preparaste su defensa en la entrevista, donde cada pregunta es una decisión de diseño que puedes señalar con el dedo.

Ahora mira atrás el camino completo, porque vale la pena verlo entero. Empezaste, en el Módulo 1, con un JSON suelto en una carpeta de descargas y una pregunta incómoda: ¿por qué tener el archivo no es tener el control? Aprendiste Git desde cero (Módulo 2), a exportar, normalizar, estructurar y documentar un repositorio (Módulo 3), a montar tres entornos aislados de verdad (Módulo 4), a probar en sandbox sin gastar un peso (Módulo 5), y —en este módulo— a promover con cuidado, revisar cada cambio (incluidos los de una IA), revertir con un runbook ensayado, decidir entre gratis y de pago con criterio, y validar automáticamente en cada commit. Cada módulo fue una pieza de un solo sistema, y el proyecto de hoy las reveló como lo que siempre fueron: las partes del entregable que el mercado pide por escrito.

Cruzaste la frontera que la guía prometió en su primera línea: de constructor de workflows a dueño del sistema de automatización. No porque construyas mejores workflows —eso ya lo sabías hacer—, sino porque ahora los envuelves en la disciplina que los vuelve un sistema entregable, operable y recuperable por otros. Y lo hiciste entero por el camino self-hosted Community a costo cero, sin pagar una suscripción, con herramientas estándar —Git, Docker, GitHub Actions— que se transfieren a cualquier lugar donde trabajes mañana.

Lo que sigue no está en esta guía; está en tu trabajo. Toma este artefacto y hazlo tuyo: reemplaza order-triage por un workflow real que hayas construido, con su nodo AI Agent y su API externa, y arma tu cumbre-automations con tu propio nombre. Púlelo hasta que marque cada casilla de la rúbrica. Y cuando una oferta diga "as version-controlled, documented JSON", no vas a tener que explicar que sabes hacerlo: vas a abrir el repositorio y mostrarlo. Ese es el objetivo que perseguimos desde el principio, y ya lo tienes en las manos.

Gracias por llegar hasta aquí. Vienen más retos y más sistemas que entregar, pero cruzar esta frontera —de armar flujos a poseer sistemas— vale la pena celebrarlo. No está nada mal para el camino que recorriste.

Recursos

← Anterior7. Chequeos de CI y el artefacto de portafolio