Módulo 3: Exportar, normalizar y estructurar el repositorio

1. Introducción: del editor al repositorio reproducible

Siguiente →

Descripción

Al terminar esta lección vas a poder explicar por qué el botón de descarga del editor de n8n no alcanza para entregar workflows como un profesional, vas a saber exactamente qué significa la frase "documented JSON" que aparece en las ofertas de trabajo, y vas a tener el mapa completo de las ocho lecciones que forman este módulo. También vas a reencontrarte con Cumbre —el caso de estudio de toda la guía— y con su workflow order-triage, que vas a exportar, limpiar, separar de sus credenciales, estructurar y documentar a lo largo del módulo.

Esto importa por una razón muy concreta. En los módulos anteriores aprendiste por qué conviene versionar un workflow y cómo usar Git para hacerlo: init, add, commit, diff, branch. Pero un repositorio con un archivo JSON descargado a mano desde el editor todavía no es un artefacto profesional. Es una foto suelta. Le falta lo que separa "guardé un JSON en una carpeta" de "otro desarrollador puede tomar este repositorio y entender el sistema en diez minutos": una exportación reproducible, credenciales fuera del repo, diffs que se pueden leer, y documentación de handoff. Este módulo es exactamente ese salto.

Conexión con el módulo: esta lección es el mapa, no el terreno. Aquí defines el problema (por qué exportar a mano no escala ni es reproducible), reconoces la meta (qué es "documented JSON" en la letra de las ofertas) y recibes el hilo que atraviesa las siete lecciones que siguen. La lección 2 te enseña la herramienta central: la CLI de n8n, para exportar sin depender del ratón. La 3 es la lección de seguridad del módulo: separar las credenciales del repositorio. La 4 convierte el JSON exportado en algo que da diffs limpios. La 5 le da forma al repositorio. La 6 lo documenta para el handoff. La 7 automatiza todo con un script. Y la 8 es el proyecto: tomas una instancia con varios workflows y produces un repositorio que pasaría la revisión de otro desarrollador. Una nota de límite desde ya: en este módulo no vas a construir workflows ni a configurar entornos dev/staging/prod. Construir es de las guías de fundamentos; los entornos son el Módulo 4. Aquí trabajamos sobre lo que ya sabes construir.

Del JSON suelto al artefacto que otro puede tomar

Piensa en dos formas de compartir una receta de cocina.

La primera: escribes la receta a mano en una servilleta y se la pasas a un amigo. Funciona… si el amigo eres tú dentro de una semana. Pero le faltan cosas. No dice de dónde salió, ni qué ingredientes hay que comprar antes de empezar, ni qué pasa si no tienes el molde exacto. Y si mañana mejoras la receta, tienes que escribir otra servilleta desde cero, y ahora tienes dos servilletas y no sabes cuál es la buena.

La segunda: publicas la receta en un recetario ordenado. Cada receta tiene una página con el mismo formato —para cuántas porciones, qué ingredientes, qué utensilios, los pasos numerados, una foto—. Cuando la mejoras, editas esa página y queda registro de qué cambió. Cualquiera que abra el recetario, aunque no te conozca, puede cocinar el plato sin llamarte por teléfono.

El botón de descarga del editor de n8n produce servilletas. Este módulo produce recetarios.

Vamos a ser precisos sobre qué le falta a la servilleta, porque cada carencia es una de las lecciones que siguen:

  • No es reproducible. Cada vez que descargas un workflow desde el editor, haces clic en un menú, eliges una carpeta, confirmas el nombre. Es un proceso manual, distinto cada vez, imposible de repetir igual dos veces. Si tienes doce workflows, son doce sesiones de clics. La lección 2 lo reemplaza por un comando que exporta los doce de una sola vez, siempre igual.
  • Filtra secretos. El JSON que descarga el editor puede arrastrar información que no debería salir de tu servidor. Y en el momento en que exportas también las credenciales, el riesgo es directo: estás a un git commit de publicar la llave de la API del CRM de tu cliente. La lección 3 blinda esto.
  • Da diffs ilegibles. El JSON de un workflow trae campos que cambian solos en cada guardado —un identificador de versión, una marca de tiempo, datos de prueba que dejaste pegados— aunque la lógica no haya cambiado en nada. Cuando Git te muestre el diff, vas a ver cuarenta líneas modificadas para un cambio que en realidad tocó dos. La lección 4 lo arregla.
  • No se navega solo. Un repositorio con workflow (7).json y workflow (final) copy.json en la raíz no le dice nada a nadie. La lección 5 le da una estructura donde cada archivo tiene su lugar.
  • No está documentado. El JSON dice qué hace el workflow paso a paso, pero no dice para qué existe, qué disparador lo enciende, qué credenciales necesita ni qué pasa si falla. La lección 6 agrega esa capa.

Ninguna de estas cinco cosas es opcional en un entorno profesional. Juntas son la diferencia entre un archivo y un entregable.

Reproducible: la palabra que separa un proceso de un ritual

De las cinco carencias, la primera —"no es reproducible"— merece un párrafo aparte, porque es la que más gente subestima y la que sostiene a todas las demás.

Un proceso es reproducible cuando cualquiera que siga los mismos pasos obtiene exactamente el mismo resultado, sin depender de que se acuerde de algo, sin decisiones a mitad de camino, sin "y entonces hago clic donde siempre". Piénsalo como la diferencia entre una receta escrita y un plato que solo le sale bien a la abuela. La receta escrita es reproducible: la sigue cualquiera. El plato de la abuela depende de la abuela.

Exportar con el botón del editor es el plato de la abuela. Depende de que tú estés, de que te acuerdes de exportar los quince workflows, de que elijas la misma carpeta cada vez, de que no te saltes ninguno. El día que te enfermas, o cambias de trabajo, o simplemente estás ocupado, el respaldo no se hace. Y un respaldo que a veces se hace y a veces no, en la práctica, no existe: nunca sabes si el que tienes está al día.

Exportar con un comando es la receta escrita. n8n export:workflow --all produce el mismo resultado hoy, mañana y dentro de un año, lo corras tú o lo corra un compañero, lo dispares a mano o lo dispare una máquina a las tres de la mañana. Esa es la propiedad que hace posible el resto del módulo: si el paso de exportar no fuera reproducible, no tendría sentido normalizar (lección 4) ni automatizar (lección 7), porque estarías puliendo un material que llega distinto cada vez.

Y hay una consecuencia menos obvia. Un proceso reproducible se puede automatizar; un ritual manual no. Toda la lección 7 —el script que exporta, normaliza y deja el repositorio listo con un solo comando— solo es posible porque cada paso que la compone es reproducible. La reproducibilidad no es una virtud estética: es el requisito técnico de todo lo que automatizas después.

Qué es, exactamente, "documented JSON"

Vale la pena detenerse en esta frase, porque no la inventé yo: aparece, con esas palabras o muy parecidas, en las ofertas de trabajo reales que piden a alguien que sepa entregar automatizaciones en n8n. La formulación que se repite es "delivered as version-controlled, documented JSON" —entregado como JSON versionado y documentado—.

Desármala en sus tres piezas, porque cada una es una promesa concreta:

JSON — el formato. Un workflow de n8n, por dentro, es un archivo de texto en formato JSON: una estructura de llaves, corchetes y valores que describe cada nodo, cada conexión y cada parámetro. No es un binario opaco ni una base de datos escondida. Es texto plano que puedes abrir, leer, comparar línea por línea y —esto es la clave— versionar con Git. Que el workflow sea texto es lo que hace posible todo lo demás.

version-controlled — versionado. El archivo vive en un repositorio Git, con su historia. Puedes ver cómo era el workflow hace tres semanas, quién cambió qué, y volver a una versión que funcionaba si la última rompió algo. Esto ya lo trabajaste en el Módulo 2. Aquí lo llevamos a que la versión que guardas sea limpia y reproducible, no una foto ruidosa tomada a mano.

documented — documentado. El repositorio incluye la información que el JSON no dice por sí solo: para qué sirve el workflow, cómo se dispara, qué credenciales requiere, qué variables usa, cómo se despliega. Suficiente para que otro desarrollador —o tú en seis meses, que a efectos prácticos es otra persona— lo tome sin necesidad de que le expliques nada en persona.

Cuando una oferta pide "documented JSON", está describiendo con dos palabras todo lo que produces en este módulo. No es un requisito decorativo: es la prueba de que quien entrega el trabajo piensa como dueño de un sistema y no como alguien que armó un flujo bonito y se fue. En una entrevista, poder mostrar un repositorio así vale más que enumerar cuántos nodos conoces.

Una aclaración honesta desde el principio, porque esta guía no te va a vender humo. n8n tiene una función de control de versiones con Git nativo, integrada en el producto, que conecta tu instancia directamente con un repositorio y sincroniza los workflows sin que toques la línea de comandos. Suena ideal. El detalle es que esa función vive en el plan Enterprise, es decir, se paga. Todo el flujo que enseña este módulo —exportar por CLI, normalizar, estructurar, documentar, automatizar con un script— logra el mismo resultado, "version-controlled, documented JSON", usando solo la edición Community, que es gratuita y self-hosted. La lección 7 vuelve sobre esta comparación con detalle y te da el criterio para decidir cuándo el flujo manual es suficiente y cuándo vale la pena pagar por el nativo. Por ahora quédate con esto: no necesitas Enterprise para entregar como profesional. Necesitas método, y el método es este módulo.

El caso de estudio: Cumbre y su workflow order-triage

Toda la guía trabaja sobre la misma empresa inventada, y este módulo no es la excepción. Si vienes de los módulos anteriores ya la conoces; si llegaste directo aquí, esta es la versión corta.

Cumbre es una distribuidora mayorista latinoamericana de café y té. Le vende a cientos de cafeterías y tiendas pequeñas repartidas en varias ciudades, y como es un equipo chico, automatiza casi todo lo que puede con n8n. A lo largo del tiempo su instancia acumuló varios workflows: uno que sincroniza inventario, uno que arma reportes semanales, uno que responde correos de soporte, y el que nos va a acompañar en este módulo:

order-triage es el workflow que recibe los pedidos que entran, los clasifica y decide qué hacer con cada uno. Por dentro tiene tres piezas que vas a ver una y otra vez:

PiezaQué haceQué implica para el repositorio
Un disparador tipo WebhookRecibe el pedido cuando entra, como un JSONDefine cómo se enciende el workflow; hay que documentarlo
Un nodo AI AgentClasifica el pedido (prioridad, categoría, si necesita revisión humana)Depende de una credencial de modelo de lenguaje
Un nodo HTTP RequestConsulta el CRM para traer los datos del clienteDepende de una credencial de acceso al CRM

Fíjate en la última columna, porque es la que hace de order-triage el caso perfecto para este módulo. Es un workflow con dos credenciales distintas —la del modelo de IA y la del CRM—, y las credenciales son justo lo que nunca puede terminar en el repositorio. Un workflow sin credenciales sería un ejemplo demasiado fácil; order-triage te obliga a resolver el problema de verdad.

El repositorio donde va a vivir todo esto se llama cumbre-automations. Y aunque en este módulo nos concentramos en exportar y estructurar, conviene que sepas hacia dónde va: en el Módulo 4 ese mismo repositorio va a organizar tres entornos —dev, staging y prod—, cada uno con su propia configuración. Lo que estructuras aquí es la base sobre la que se para todo lo demás.

Una nota de honestidad, como siempre con Cumbre: es una empresa inventada. Los nombres de sus workflows, sus credenciales y sus datos son hipótesis razonables para practicar, no información de una empresa real. Lo que se transfiere a tu trabajo no son los datos de Cumbre, sino la forma de organizarlos.

La instancia completa, no un solo workflow

Aunque order-triage es el protagonista, conviene que veas el cuadro completo desde ahora, porque el proyecto de la lección 8 no exporta un workflow: exporta toda la instancia de Cumbre. Un repositorio profesional casi nunca contiene un archivo suelto; contiene el sistema entero de una organización, con todas sus piezas conviviendo de manera ordenada.

Esta es la instancia de Cumbre tal como la vamos a tratar en el módulo:

WorkflowQué haceCredenciales que usa
order-triageRecibe pedidos, los clasifica con IA y consulta el CRMModelo de lenguaje + CRM
inventory-syncSincroniza el inventario contra la tienda en línea cada horaAPI de la tienda
weekly-reportArma y envía el reporte de ventas de la semanaBase de datos + correo
support-autoresponderResponde correos de soporte de primer nivelCorreo + modelo de lenguaje

Cuatro workflows, varias credenciales compartidas entre ellos, y un solo repositorio que tiene que albergarlos a todos sin que se pisen. Ese es el escenario realista. Cuando en la lección 2 corras n8n export:workflow --all, los cuatro van a salir de una vez; cuando en la lección 5 estructures el repositorio, vas a tener que decidir dónde vive cada uno; y cuando en la lección 8 entregues, el criterio va a ser si otro desarrollador puede abrir cumbre-automations y entender los cuatro sin ayuda.

Por ahora, quédate con order-triage en el centro de la atención —es sobre el que vamos a trabajar comando por comando— y con la conciencia de que no está solo en la instancia. Un repositorio de un solo workflow es un ejercicio; uno de una instancia completa es el trabajo real.

Ejemplo trabajado: qué te da el editor y qué queremos en su lugar

Vamos a mirar de frente el punto de partida. Sin escribir todavía ningún comando, veamos qué pasa hoy cuando exportas order-triage con el botón del editor.

Abres el workflow en n8n, entras al menú de tres puntos, eliges "Download", y el navegador te guarda un archivo. Lo llamas, digamos, order-triage.json. Lo abres y ves algo con esta forma (recortado, porque el real tiene cientos de líneas):

{
  "name": "order-triage",
  "nodes": [
    {
      "parameters": { "httpMethod": "POST", "path": "new-order" },
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [ 240, 300 ]
    }
  ],
  "connections": { },
  "active": true,
  "pinData": {
    "Webhook": [ { "json": { "order_id": "ORD-2041", "customer_name": "Luna Coffee" } } ]
  },
  "versionId": "e7f8a9b0-1111-2222-3333-444455556666",
  "meta": { "instanceId": "9c8b7a6d5e4f3a2b1c0d..." }
}

Ese archivo funciona: si lo importas en otra instancia, reconstruye el workflow. Pero como entregable tiene tres problemas que este módulo resuelve, y conviene que los reconozcas desde ahora:

Primero, mira pinData. Ahí quedó pegado un pedido de prueba —Luna Coffee, ORD-2041— que usaste mientras armabas el workflow. Es basura para el repositorio: cambia cada vez que pruebas con otro dato, y no describe la lógica en nada. La lección 4 lo quita.

Segundo, mira versionId y meta.instanceId. Son identificadores que n8n regenera solo. versionId cambia en cada guardado, aunque no hayas tocado la lógica; instanceId identifica tu servidor y no tiene por qué viajar. Si haces git diff mañana después de guardar sin cambiar nada, Git te va a marcar estas líneas como modificadas. Ruido puro. La lección 4 también los quita.

Tercero, y es el que da miedo: este workflow usa dos credenciales, pero en este recorte no se ven porque el editor las referencia por identificador, no por valor. Eso es bueno —el valor de la credencial no está en este archivo—. Pero el momento en que exportes las credenciales para respaldarlas, vas a tener archivos con secretos reales, y si no tienes un .gitignore puesto antes, un git add . distraído los sube al repositorio. La lección 3 se dedica entera a que eso nunca pase.

Lo que queremos en su lugar es un archivo exportado por comando (reproducible), sin pinData ni identificadores volátiles (diff limpio), con las claves ordenadas siempre igual, acompañado de un .gitignore que blinda los secretos y de un README que explica qué es order-triage. Ese es el destino del módulo. Hoy tienes la servilleta; en la lección 8 vas a tener el recetario.

Por qué estructurar el repo va antes de montar entornos

Quizás te preguntes por qué este módulo —exportar y estructurar— viene antes del Módulo 4, que monta los entornos dev, staging y prod. La intuición podría ser la contraria: primero tener los entornos, después llenarlos.

El orden es deliberado, y la razón es concreta. Un entorno de staging no es más que una segunda instancia de n8n donde corre una copia de tus workflows para probarlos antes de que lleguen a producción. ¿Y de dónde sale esa copia? Del repositorio. Promover un workflow de dev a staging, que es lo que hace el Módulo 6, es tomar el JSON del repositorio e importarlo en la otra instancia. Si el JSON del repositorio está sucio —con datos de prueba pegados, con el instanceId del servidor equivocado, con una credencial filtrada—, todo lo que construyas encima hereda esa suciedad.

Dicho de otra forma: el repositorio limpio y reproducible que produces en este módulo es la fuente de verdad de la que van a beber los tres entornos. Por eso va primero. No se puede promover bien lo que no está exportado bien.

El hilo del módulo, lección por lección

Este es el mapa, para que cada lección se sienta un paso de un camino y no una cápsula suelta:

LecciónQué resuelveCon qué herramienta
2Exportar sin depender del ratón, en lote y siempre igualLa CLI de n8n (n8n export:workflow)
3Que ninguna credencial —ni cifrada— termine en el repon8n export:credentials, N8N_ENCRYPTION_KEY, .gitignore
4Que el diff muestre solo lo que de verdad cambióUn script de normalización con jq o Node
5Que el repositorio se navegue soloUn layout con workflows/, credentials/, docs/, scripts/
6Que otro desarrollador lo tome sin llamarteREADME por workflow + sticky notes en el canvas
7Hacer todo lo anterior con un solo comandoUn script de shell (export.sh) + git hook opcional
8Juntar todo en un repositorio entregableEl proyecto: de instancia a repo documentado

El orden no es arbitrario. Primero consigues el material limpio (exportar, separar credenciales, normalizar: lecciones 2 a 4). Después le das forma y sentido (estructura y documentación: 5 y 6). Y recién entonces lo automatizas (7), porque automatizar un proceso que todavía no entiendes es automatizar tus errores. El proyecto (8) es la prueba de que las siete piezas encajan.

Una imagen que puede ayudarte: las lecciones 2, 3 y 4 son sacar la pieza de la máquina y limpiarla. Las lecciones 5 y 6 son ponerla en su estuche etiquetado. La lección 7 es construir la máquina que hace eso sola. Y la 8 es entregar el estuche a otra persona y que lo entienda.

Qué vas a poder hacer al terminar el módulo

Al final de la lección 8 vas a poder:

  • Exportar cualquier workflow de tu instancia con la CLI de n8n, uno por uno o todos de golpe, sin tocar el editor.
  • Separar las credenciales de los workflows y garantizar, con un .gitignore correcto, que ningún secreto llegue al repositorio ni siquiera por accidente.
  • Normalizar el JSON exportado para que los diff de Git sean legibles y los conflictos de fusión, raros.
  • Estructurar y documentar un repositorio de manera que otro desarrollador lo entienda sin ayuda.
  • Automatizar todo el proceso en un solo comando que corres antes de cada commit.

Lo que no vas a hacer todavía, y está bien: montar entornos aislados, promover un workflow de dev a prod, o probar en un sandbox con datos sintéticos. Eso es de los módulos 4, 5 y 6. Este módulo produce el repositorio limpio sobre el que esos módulos van a operar.

Errores comunes

Creer que "ya está en Git" significa "ya está entregable" (conceptual). Qué pasa: alguien descarga su workflow del editor, hace git init, git add ., git commit, y da el trabajo por terminado. Técnicamente hay un repositorio. Pero adentro hay un JSON con datos de prueba pegados, identificadores volátiles, cero documentación y —en el peor caso— una credencial exportada por accidente. Por qué pasa: los módulos 1 y 2 enseñan que versionar es el objetivo, y es fácil confundir "está bajo control de versiones" con "está listo para entregar". Son cosas distintas: la primera es el contenedor, la segunda es la calidad de lo que metes adentro. Cómo detectarlo: abre tu repositorio y pregúntate si un desconocido podría tomarlo y entender qué hace cada workflow, qué necesita para correr y cómo se despliega, sin escribirte a ti. Si la respuesta es no, tienes un contenedor, no un entregable. Cómo corregirlo: es literalmente el resto de este módulo. No te saltes la lección 3 pensando que la seguridad "ya la tienes cubierta": es la que más gente ignora y la que más caro se paga.

Tratar el botón de descarga del editor como un método de respaldo serio (conceptual). Qué pasa: alguien respalda sus workflows descargándolos a mano cada tanto, y cuando tiene quince workflows, el respaldo se vuelve una tarea de media hora que nadie hace. Por qué pasa: el botón funciona bien para uno o dos workflows, así que el problema no aparece hasta que ya es tarde. Cómo detectarlo: si tu "respaldo" depende de que te acuerdes de hacer clic quince veces, no es un respaldo, es una intención. Cómo corregirlo: la CLI de la lección 2 exporta todo de un comando, y el script de la lección 7 hace que ese comando corra solo. El respaldo confiable es el que no depende de tu memoria.

Suponer que un workflow cifrado se puede subir al repositorio "porque está cifrado" (conceptual, y peligroso). Qué pasa: alguien razona que si las credenciales salen cifradas, subirlas al repo es seguro. No lo es, y la lección 3 explica exactamente por qué. Por qué pasa: "cifrado" suena a "a salvo", y es una intuición razonable pero incompleta. Cómo detectarlo: si en algún momento piensas "esto está cifrado, entonces lo puedo commitear", detente. Cómo corregirlo: la regla que vas a aprender en la lección 3 es más simple y más segura: las credenciales, en cualquier forma, viven fuera del repositorio, y un .gitignore puesto desde el primer commit lo garantiza.

Ejercicios

Ejercicio 1 — Encuentra "documented JSON" en el mercado. Busca tres ofertas de trabajo reales que mencionen n8n (en LinkedIn, en bolsas de trabajo remotas o en canales de la comunidad). Para cada una, anota si menciona alguna de estas ideas, con las palabras que use: entregar en Git / control de versiones, documentación / handoff, JSON versionado, o que otro desarrollador pueda retomar el trabajo. Cuenta cuántas de las tres piden, de alguna forma, lo que este módulo produce.

Ver solución

No hay una respuesta única, y ese es el punto. Lo que la mayoría de las personas encuentra es que las ofertas mejor pagadas —las remotas en dólares, las de agencias de automatización— casi siempre incluyen alguna frase sobre entregar el trabajo versionado y documentado, mientras que las ofertas más junior se quedan en "sabe usar n8n". Esa diferencia no es casual: describe a alguien que posee un sistema frente a alguien que lo arma y se va.

Si de tus tres ofertas ninguna menciona nada de esto, tienes dos hipótesis igual de válidas: o tomaste una muestra muy junior, o el mercado de tu región va con cierto retraso respecto del promedio remoto. Amplía a seis ofertas antes de concluir.

Por qué funciona: este módulo enseña una habilidad que es fácil de subestimar porque no "hace" nada visible —no construye un workflow nuevo—. Ver con tus propios ojos que el mercado la pide por escrito convierte una tarea que parece burocrática en una ventaja concreta de contratación.

Ejercicio 2 — Diagnostica una servilleta. Vuelve al ejemplo trabajado de esta lección, el JSON que descarga el editor. Para cada uno de estos cuatro elementos, di en una frase si debería o no viajar al repositorio, y por qué: (a) el arreglo nodes con la definición de cada nodo; (b) el campo pinData con el pedido de prueba de Luna Coffee; (c) el campo versionId; (d) el valor de la credencial del CRM.

Ver solución

(a) Sí viaja. nodes es la lógica del workflow: qué nodos hay, cómo están configurados, cómo se conectan. Es exactamente lo que queremos versionar. Sin esto no hay workflow.

(b) No viaja. pinData son datos de prueba que dejaste pegados mientras editabas. Cambian según con qué pruebes, no describen la lógica, y ensucian cada diff. La lección 4 los quita en la normalización.

(c) No viaja. versionId es un identificador que n8n regenera en cada guardado. Marcarlo como cambio en el diff es puro ruido: cambia aunque la lógica no. También se quita en la lección 4.

(d) Jamás viaja. El valor de una credencial —la llave real del CRM— nunca entra al repositorio, en ninguna forma. Es el punto de seguridad del módulo y el tema completo de la lección 3.

Por qué funciona: separar lo que es lógica (viaja) de lo que es estado volátil (no viaja) de lo que es secreto (jamás viaja) es el criterio que gobierna todo este módulo. Si tienes claro a cuál de las tres categorías pertenece cada campo, ya entendiste la idea central antes de correr un solo comando.

Ejercicio 3 — Reconstruye el hilo. Sin volver a mirar la tabla del hilo del módulo, escribe de memoria qué resuelve cada una de las siete lecciones que siguen (2 a 8), en una frase cada una. Después compara y marca las que se te escaparon.

Ver solución

(2) Exportar workflows con la CLI de n8n, en lote y de forma reproducible. (3) Separar las credenciales del repositorio para que ningún secreto se suba, ni cifrado. (4) Normalizar el JSON quitando campos volátiles para obtener diffs limpios. (5) Estructurar el repositorio con un layout que se navega solo. (6) Documentar cada workflow para que otro desarrollador lo retome. (7) Automatizar exportación y normalización con un solo script. (8) El proyecto: convertir una instancia completa en un repositorio documentado.

Por qué funciona: si reconstruiste al menos cinco de las siete, ya internalizaste la progresión —conseguir material limpio, darle forma y sentido, automatizarlo, entregarlo—. Las que más se escapan suelen ser la 4 (normalización) y la 7 (automatización), que son las más abstractas hasta que las ves funcionando sobre order-triage.

Resumen y siguiente paso

En esta lección viste por qué un JSON descargado a mano desde el editor de n8n todavía no es un entregable profesional: no es reproducible, filtra secretos, da diffs ilegibles, no se navega solo y no está documentado. Cada una de esas cinco carencias es una de las lecciones que siguen. Desarmaste la frase que el mercado pide por escrito —"version-controlled, documented JSON"— en sus tres promesas: texto versionable, historia bajo control y documentación de handoff. Y reencontraste a Cumbre con su workflow order-triage, que recibe pedidos por Webhook, los clasifica con un nodo AI Agent y consulta el CRM por HTTP, con sus dos credenciales que lo convierten en el caso perfecto para practicar la separación de secretos. Todo esto va a vivir en el repositorio cumbre-automations.

Antes de avanzar a la lección 2 deberías poder: explicar en una frase la diferencia entre "está en Git" y "está entregable"; nombrar las tres piezas de "documented JSON"; y describir qué hace order-triage y por qué sus dos credenciales lo hacen un buen caso de estudio.

La lección 2 empieza el trabajo de verdad. Vas a conocer la CLI de n8n: qué es, cómo se corre —según si tu instancia está instalada con npm o corre dentro de Docker—, y cómo exportar order-triage con un comando en lugar de quince clics. Es el primer paso para dejar de producir servilletas.

Recursos

← Anterior8. Proyecto: un workflow bajo control de versionesSiguiente →2. Exportar con la CLI de n8n