2. Promover workflows entre entornos

Descripción

Al terminar esta lección vas a poder promover un workflow de un entorno al siguiente con la CLI de n8n: exportarlo del origen e importarlo en el destino con import:workflow, decidir si llega activo o inactivo, y entender por qué las credenciales son el punto delicado de toda promoción. Vas a conocer import:credentials y su papel en el destino, vas a saber qué revisar antes de promover para no romper producción, y vas a llevar order-triage de staging a prod paso a paso, como se hace en un despliegue de verdad.

Esto importa porque promover es el eslabón que convierte tu repositorio en algo que de verdad llega a producción. Hasta ahora versionaste, montaste entornos y probaste; todo eso vale poco si el cambio probado en staging no puede pasar a prod de forma controlada. Y "de forma controlada" es la clave: importar un workflow es un comando de una línea, pero hacerlo sin romper los pedidos reales de Cumbre requiere entender qué se rompe al mover un workflow entre instancias —justo el problema de portabilidad que estudiaste en los Módulos 1 y 3— y cómo la separación de credenciales por entorno del Módulo 4 lo resuelve.

Conexión con el módulo: la lección 1 te mostró el pipeline completo; esta ejecuta su penúltimo eslabón, promover. Aquí usas el import:workflow que en el Módulo 3 apenas asomaste como "el camino de vuelta", y lo conectas con las credenciales por entorno del Módulo 4. La lección 3 te enseña a revisar el diff antes de esta promoción; la lección 5 te enseña a revertir si la promoción sale mal. Así que esta lección es el movimiento hacia adelante, y las que la rodean son su control de calidad y su red de seguridad. Presta atención a la decisión de activación y al mapeo de credenciales, porque son los dos lugares donde una promoción ingenua rompe producción en silencio.

Qué es promover, y por qué no es solo importar

Empecemos por definir la palabra, porque se usa mucho y a veces flojamente.

Promover un workflow es llevar una versión ya probada de un entorno a otro más cercano a producción: de dev a staging, o de staging a prod. La palabra viene del mundo del desarrollo de software, donde un cambio "se promueve" por una serie de ambientes, ganándose el paso a cada uno solo después de pasar sus pruebas. No es mover el workflow de cualquier forma; es moverlo hacia adelante en una cadena de confianza, donde cada eslabón es más real y menos perdonador que el anterior.

Piénsalo como un ascenso en una empresa. Un empleado nuevo no llega el primer día a dirigir la operación crítica. Empieza en un puesto donde puede aprender y equivocarse sin consecuencias graves (dev), demuestra que rinde en un puesto más exigente pero todavía supervisado (staging), y solo cuando probó que aguanta la presión lo ascienden al puesto donde sus errores cuestan de verdad (prod). Nadie asciende a alguien saltándose los escalones, y nadie lo asciende sin revisar su desempeño. Promover un workflow es exactamente ese ascenso: mismo "empleado" —la lógica del workflow—, en un puesto de más responsabilidad.

Aquí está el matiz que esta lección existe para instalar: promover no es solo correr import:workflow. El comando es la mecánica —el papeleo del ascenso—, pero la promoción es todo lo que lo rodea: revisar el cambio antes (lección 3), mapear las credenciales del destino, decidir si el workflow llega activo, y tener el rollback listo por si algo falla (lección 5). Alguien que solo corre el comando está firmando el ascenso sin leer el expediente. Vamos a leer el expediente.

La anatomía de una promoción

Toda promoción tiene la misma forma, sin importar entre qué entornos ocurra. Son tres movimientos:

1. Sacar la versión buena del origen. No cualquier versión: la que ya pasó las pruebas. Y en un flujo profesional, no la sacas de la instancia viva de staging, sino del repositorio, que es la fuente de verdad. El JSON que vas a promover es el que está commiteado en cumbre-automations, revisado y aprobado.
2. Meter esa versión en el destino. Con import:workflow, apuntando a la instancia del entorno de destino (prod). Aquí es donde el workflow "aterriza" en su nueva cocina.
3. Ajustar lo que cambia por entorno. Un workflow no es solo su lógica; también tiene credenciales (que en prod son las reales, no las de prueba) y un estado de activación (¿debe empezar a correr apenas llega, o quedar inactivo hasta que alguien lo encienda?). Estos ajustes son el "papeleo del ascenso" y son donde una promoción se rompe si no se cuidan.

Fíjate en una decisión de fondo que atraviesa los tres movimientos, y que ya conoces del modelo "workflow como código": la lógica viaja, la configuración no. El JSON del workflow —los nodos, las conexiones, cómo está armado— es igual en los tres entornos: es la receta, y la receta es una sola. Lo que cambia entre staging y prod no es la receta, son los ingredientes: en staging usas ingredientes de práctica (credenciales de prueba, el CRM sandbox), en prod los reales (el CRM de verdad de Cumbre). Promover bien es mover la receta sin mover los ingredientes de prueba a la cocina real por accidente.

import:workflow: meter el workflow en el destino

El comando central de la promoción es el espejo del export:workflow que ya dominas. Donde export saca workflows de una instancia a archivos, import mete archivos de vuelta a una instancia. Su bandera principal es --input, el reflejo exacto de --output.

Estas son sus banderas, confirmadas contra la documentación oficial de n8n a julio de 2026. Como siempre, corre n8n import:workflow --help en tu instancia antes de confiar en cualquiera: tu versión manda sobre esta guía.

Bandera	Qué hace
--input=<ruta>	De dónde leer: un archivo (order-triage.json) o, con --separate, una carpeta.
--separate	Importa todos los archivos .json de la carpeta que indica --input. El espejo de --separate en export.
--projectId=<id>	Importa a un proyecto específico de la instancia de destino. No se combina con --userId.
--userId=<id>	Importa asignándolo a un usuario específico. No se combina con --projectId.
--activeState	Controla si el workflow queda activo al importar. Acepta false (por defecto) o fromJson (solo en modo multi-main).
--skipMigrationChecks	Salta las validaciones de migración de versión. Úsalo solo si sabes por qué lo necesitas.
--help	Imprime esta lista para tu versión.

Presta atención especial a --activeState, porque encierra una de las dos trampas de la promoción. Vamos a ella en un momento; primero, la forma básica del comando.

Para promover order-triage, corres el import:workflow contra la instancia de destino. Si tus entornos corren en Docker —el caso de esta guía—, cada entorno es su propio contenedor, así que el docker exec apunta al contenedor de prod:

docker exec -u node -it n8n-prod n8n import:workflow --input=order-triage.json

Desármalo con los ojos de la lección 2 del Módulo 3, que ya te enseñó a leer estos comandos:

• docker exec -u node -it n8n-prod — "ejecuta adentro del contenedor de producción, como el usuario node, con una terminal". Fíjate en el nombre del contenedor: n8n-prod. Aquí es donde el aislamiento del Módulo 4 se vuelve concreto: hay un contenedor por entorno, y promover a prod significa apuntarle a ese contenedor, no al de staging.
• n8n import:workflow — el comando, espejo de export:workflow.
• --input=order-triage.json — el archivo a importar, que es el JSON versionado y probado que sacaste del repositorio.

Un detalle de importancia que confunde la primera vez: igual que al exportar, los archivos que import lee tienen que estar donde el comando corre. Si el comando corre dentro del contenedor de prod, el order-triage.json tiene que estar accesible ahí adentro —por un volumen compartido o copiándolo con docker cp antes—. Es la misma lógica de fronteras de contenedor de la lección 2 del Módulo 3, ahora en la dirección de entrada.

Crear contra actualizar: qué pasa si el workflow ya existe

Aquí hay una sutileza que decide si tu promoción crea un workflow nuevo en prod o actualiza el que ya está ahí. La regla, que conviene verificar en tu versión porque toca el comportamiento fino del importador, es esta: n8n usa el identificador del workflow (el campo id del JSON) para decidir. Si en prod ya existe un workflow con ese mismo id, el import lo actualiza —sobrescribe su lógica con la del archivo—. Si no existe ninguno con ese id, lo crea.

Esto es exactamente lo que quieres para promover: la segunda vez que promueves order-triage a prod, no quieres un segundo order-triage duplicado, quieres que el existente se actualice a la versión nueva. Que el id viaje en el JSON y coincida entre entornos es lo que hace que la promoción actualice en vez de duplicar.

Y aquí se cierra un círculo que abriste en el Módulo 1: recuerda que en el proyecto del Módulo 3 se advertía contra "duplicar los workflows por entorno". Ahora ves por qué importaba. Si cada entorno tuviera su propia copia con su propio id, promover crearía duplicados sin fin. Como la lógica se versiona una vez, con un id estable, promover siempre actualiza la versión correcta en el destino. Un workflow, muchos entornos.

La trampa número uno: las credenciales del destino

Este es el corazón peligroso de la lección, y el punto donde una promoción ingenua rompe producción de la peor forma: en silencio, sin dar error.

Recuerda del Módulo 1 qué contiene el JSON de un workflow respecto de las credenciales: no contiene los secretos, contiene referencias. Cada nodo que necesita una credencial —el nodo AI Agent, el nodo HTTP Request al CRM— guarda en su JSON un bloque como este:

"credentials": {
  "httpHeaderAuth": {
    "id": "aB3xK9",
    "name": "Cumbre CRM key"
  }
}

Ese bloque dice "yo uso la credencial con id aB3xK9, que se llama Cumbre CRM key". Es un puntero, no la llave. La llave real —el token del CRM— vive cifrada en la base de datos de la instancia, nunca en el JSON. Eso es lo que hace seguro versionar el workflow: el secreto no está ahí.

Pero ese puntero crea un problema al promover. Cuando importas order-triage en prod, el nodo HTTP Request llega diciendo "yo uso la credencial aB3xK9". Y ahora la pregunta crítica: ¿existe en la instancia de prod una credencial que ese puntero pueda resolver?

• Si en prod existe una credencial que el import pueda emparejar con esa referencia —con el mismo id, o que el flujo de tu Módulo 4 dejó alineada por nombre—, el nodo la usa y el workflow funciona. Y como en prod esa credencial contiene el token del CRM real de Cumbre, el workflow habla con el CRM real. Perfecto: eso es lo que quieres.
• Si en prod no existe nada que resuelva esa referencia, el nodo queda con una credencial "colgando", sin asignar. El workflow importó sin error —el comando dice "éxito"—, pero al ejecutarse, el nodo del CRM falla porque no tiene con qué autenticarse. Y ahí está el silencio: la promoción "funcionó", pero el workflow está roto, y no te enteras hasta que un pedido real intenta pasar y no puede.

Aquí es donde el Módulo 4 te salvó por adelantado. En ese módulo montaste credenciales por entorno: cada entorno tiene sus propias credenciales, con las de prueba en dev/staging y las reales en prod, pero pensadas para que la referencia del workflow resuelva en cada uno. La estrategia limpia es que la credencial se llame igual en los tres entornos —Cumbre CRM key— aunque su contenido sea distinto: en staging apunta al CRM sandbox, en prod al CRM real. Así, el mismo order-triage.json funciona en los tres, porque en cada instancia el puntero encuentra una credencial que resolver, con el ingrediente correcto para esa cocina.

import:credentials: el rol de las credenciales en el destino

El comando espejo para las credenciales es import:credentials. Tiene casi las mismas banderas que import:workflow —--input, --separate, --projectId, --userId— y sirve para meter credenciales exportadas en una instancia.

Pero aquí hace falta una advertencia fuerte, que arrastra toda la disciplina de seguridad del Módulo 3. En un flujo profesional, no promueves las credenciales de prod importándolas desde un archivo del repositorio, porque las credenciales reales nunca viven en el repositorio. Ese es el pilar de seguridad de toda la guía: los secretos no se versionan. Entonces, ¿para qué sirve import:credentials en la promoción?

Su uso legítimo es el montaje inicial del entorno, no el ciclo de cada cambio. Cuando levantas prod por primera vez (Módulo 4), tienes que poblarlo con sus credenciales reales una vez. Puedes hacerlo de dos formas honestas:

• A mano en el editor, creando cada credencial de prod con su valor real. Es lo más transparente y lo recomendado para pocas credenciales.
• Con import:credentials desde un respaldo cifrado seguro que vive fuera del repositorio —como el ~/secure-backups/ del proyecto del Módulo 3—, y sin --decrypted. Aquí el archivo de credenciales no está en el repo; está en tu bóveda, y solo lo usas para poblar la instancia. Para que se descifre al importar, la instancia de destino tiene que tener la misma N8N_ENCRYPTION_KEY con la que se cifró.

La regla que conviene grabar: el workflow se promueve en cada cambio; las credenciales se establecen una vez por entorno. Mezclar los dos —tratar de "promover credenciales" en cada ciclo desde el repo— es el camino directo a filtrar un secreto o a romper la seguridad que tanto cuidaste. La promoción diaria mueve la lógica; las credenciales ya están puestas en cada entorno desde que lo montaste.

La trampa número dos: activo o inactivo al llegar

La segunda forma de romper prod con una promoción es sutil y tiene que ver con el timing. Cuando importas un workflow, ¿debe empezar a correr apenas llega, o quedar inactivo hasta que tú lo enciendas deliberadamente?

Un workflow activo es uno que está escuchando y ejecutándose: si order-triage está activo en prod, su Webhook está recibiendo pedidos reales y su lógica los está procesando. Un workflow inactivo está importado pero dormido: existe, pero no recibe ni procesa nada hasta que alguien lo activa.

La decisión importa porque promover a prod con el workflow llegando activo de golpe es arriesgado. Imagina que promueves una versión de order-triage que —sin que lo hayas notado— tiene un bug. Si llega activa, empieza a procesar pedidos reales inmediatamente, con el bug, antes de que puedas verificar nada. Si en cambio llega inactiva, tienes una ventana para revisar que todo esté en su lugar —las credenciales resueltas, la configuración correcta— y después la activas con intención, mirando.

Por eso el comportamiento por defecto de import:workflow es traer el workflow inactivo: la bandera --activeState tiene el valor false por defecto. Es una decisión de diseño prudente de n8n: importar no enciende nada; encender es un acto aparte y deliberado. El valor fromJson —que le diría "activa según lo que diga el JSON"— solo funciona en el modo multi-main de n8n (una configuración avanzada de escalado que esta guía no cubre), así que en la práctica, en tu setup, los workflows importados llegan inactivos y tú los activas cuando estás listo.

Esto es exactamente lo que quieres para una promoción segura. El flujo prudente es: importas (llega inactivo) → verificas que las credenciales resuelven y todo está en su lugar → activas a mano en el editor de prod, mirando. Nunca "importar y que arranque solo". El workflow llega, tú lo revisas, tú lo enciendes. Ese pequeño paso manual entre "llegó" y "está corriendo" es una de las razones por las que la promoción por CLI es segura: te da un momento para respirar antes de que los pedidos reales entren.

Qué revisar antes de promover a prod

Antes de correr el import:workflow contra prod, un dueño del sistema pasa una lista de verificación. No es burocracia: es lo que evita que rompas los pedidos reales de Cumbre. Esta es la lista, y cada punto previene un desastre concreto:

• ¿El cambio pasó por staging y por su prueba en sandbox? Nunca promuevas a prod algo que no probaste primero en un entorno más seguro. Es el principio del ascenso: se gana el paso, no se salta. (La prueba es el Módulo 5.)
• ¿Revisaste el diff de lo que estás promoviendo? Tienes que saber exactamente qué cambió respecto de lo que hay en prod hoy. Un diff limpio de dos líneas es seguro; un diff que no entiendes es una alarma. (La revisión es la lección 3, la que sigue.)
• ¿Las credenciales que el workflow referencia existen en prod, con los valores reales? Si el workflow usa Cumbre CRM key y Cumbre LLM key, confirma que prod tiene esas credenciales pobladas con los secretos de producción antes de promover. Si no, el workflow importará pero fallará al correr.
• ¿Tienes el rollback listo? Antes de tocar prod, sabe cuál es el último JSON bueno y cómo volver a él. Nunca promuevas sin saber cómo deshacer. (El rollback es la lección 5.)
• ¿Vas a importarlo inactivo y activarlo a mano después de verificar? Confirma que no vas a encender producción a ciegas.

Fíjate en el patrón: de los cinco puntos, tres apuntan a otras lecciones. Eso no es accidente. La promoción segura es el ciclo completo del módulo trabajando junto: pruebas (Módulo 5), revisas (lección 3), promueves (esta lección) y tienes cómo revertir (lección 5). El comando import:workflow es solo el instante en que aprietas el gatillo; la seguridad está en todo lo que hiciste antes de apretarlo.

Ejemplo trabajado: promover order-triage de staging a prod

Vamos a hacerlo completo, con Cumbre. El escenario: en staging probaste una versión nueva de order-triage —le agregaste un umbral que manda a revisión manual los pedidos de más de 5000 pesos—, la pasada de sandbox pasó, y ahora la promueves a prod. Asumimos el escenario Docker de la guía, con contenedores n8n-staging y n8n-prod.

Paso 0 — Dónde estás. Estás parado en el repositorio, con el order-triage.json versionado que ya probaste, y con prod corriendo en su contenedor n8n-prod con sus credenciales reales ya puestas (desde que montaste el entorno en el Módulo 4).

cd cumbre-automations

Qué esperar: git status limpio, git log mostrando el commit del cambio que vas a promover. La versión que vas a llevar a prod es la que está en workflows/order-triage.json, no la que esté "viva" en staging. Sacas de la fuente de verdad, no de la instancia.

Paso 1 — Verifica el diff (adelanto de la lección 3). Antes de mover nada, mira qué cambió respecto de lo que corre en prod:

git diff HEAD~1 workflows/order-triage.json

Qué esperar: gracias a la normalización del Módulo 3, el diff muestra solo las líneas del cambio real —el umbral de 5000 y el nodo de revisión manual— y nada de ruido. Si vieras cambios que no esperas, esa es tu señal de alto: no promuevas lo que no entiendes. (La lección 3 profundiza en leer este diff.)

Paso 2 — Confirma las credenciales en prod. Antes de importar, asegúrate de que prod tiene las credenciales que order-triage referencia. Puedes listarlas o simplemente abrir el editor de prod y verificar que existen Cumbre CRM key y Cumbre LLM key, pobladas con los valores reales. Este paso es de verificación, no de importación: las credenciales de prod ya deberían estar ahí desde el montaje del entorno.

Qué esperar: confirmas que las dos credenciales existen en prod con sus valores de producción. Si faltara alguna, la creas ahora en el editor de prod con su valor real, antes de importar el workflow.

Paso 3 — Hacer llegar el JSON al contenedor de prod. El import lee desde dentro del contenedor, así que el archivo tiene que estar accesible ahí. Si tu prod monta un volumen compartido, copia el archivo a esa carpeta; si no, usa docker cp:

docker cp workflows/order-triage.json n8n-prod:/tmp/order-triage.json

Qué esperar: el order-triage.json ahora está dentro del contenedor n8n-prod, en /tmp/, listo para que el import lo lea.

Paso 4 — Importar en prod. El comando central:

docker exec -u node -it n8n-prod n8n import:workflow --input=/tmp/order-triage.json

Qué esperar: la terminal confirma algo como Successfully imported 1 workflow.. En prod, el order-triage existente se actualizó a la versión nueva (porque el id coincidía), y llegó inactivo (el comportamiento por defecto). Todavía no está procesando pedidos: está importado y dormido, esperando tu verificación.

Paso 5 — Verificar antes de encender. Abre order-triage en el editor de prod. Confirma dos cosas: que la lógica es la nueva (el nodo de revisión manual está ahí, el umbral es 5000) y que los nodos que usan credenciales —el AI Agent y el HTTP Request— muestran sus credenciales resueltas, no en rojo ni "colgando". Si algún nodo muestra la credencial sin asignar, ese es el problema de la trampa número uno: resuélvelo antes de seguir.

Qué esperar: el workflow se ve correcto y sus credenciales resuelven a las de prod. Nada está corriendo todavía.

Paso 6 — Activar, con intención. Solo ahora, mirando y con todo verificado, activas el workflow —con el interruptor de activación en el editor de prod—.

Qué esperar: order-triage pasa a activo en prod y empieza a procesar los pedidos reales con la lógica nueva. Acabas de promover un cambio a producción de forma controlada: probado, revisado, importado inactivo, verificado y encendido a propósito. Ese pequeño ritual es la diferencia entre un despliegue y un accidente.

Detente un segundo en lo que no hiciste: no editaste directo en prod, no importaste las credenciales desde el repo, no dejaste que el workflow arrancara solo antes de mirarlo. Cada cosa que no hiciste es una forma de romper producción que evitaste a propósito.

Promover en la otra dirección: de dev a staging

Todo lo que viste aplica igual para el ascenso anterior, de dev a staging, con una diferencia de tono: staging perdona más que prod, porque no procesa pedidos reales. Ahí puedes ser un poco menos ceremonioso —staging existe justamente para ensayar—, pero el flujo es el mismo: sacas la versión del repo, la importas en el contenedor de staging, verificas que las credenciales de prueba resuelven, y la activas para correr la pasada de sandbox del Módulo 5.

La forma general de cualquier promoción, entonces, es una sola, y cambia solo el contenedor de destino:

# de dev a staging
docker exec -u node -it n8n-staging n8n import:workflow --input=/tmp/order-triage.json

# de staging a prod
docker exec -u node -it n8n-prod n8n import:workflow --input=/tmp/order-triage.json

Mismo comando, distinto destino. Lo que cambia entre los dos no es el import, es cuánto cuidado pones alrededor: hacia prod, todo el ritual de verificación; hacia staging, una versión más ligera del mismo. El entorno más real merece más ceremonia.

Errores comunes

Promover sacando el workflow de la instancia viva en vez del repositorio (conceptual). Qué pasa: alguien, para promover, exporta el workflow directo de la instancia de staging en ese momento y lo importa en prod, saltándose el repositorio. Si staging tenía un cambio a medio hacer o sin commitear, ese estado sucio viaja a prod. Por qué pasa: parece más directo "de instancia a instancia" que pasar por el repo. Cómo detectarlo: si lo que promueves no coincide con lo que está commiteado en el repositorio, estás promoviendo algo no versionado. Cómo corregirlo: el repositorio es la fuente de verdad. Promueves lo que está commiteado y revisado, no lo que casualmente hay en una instancia. Sacar del repo garantiza que promueves exactamente lo que revisaste.

Importar y creer que "funcionó" porque el comando no dio error (práctico, y el más silencioso). Qué pasa: corres import:workflow en prod, la terminal dice Successfully imported, y das la promoción por hecha. Pero el nodo del CRM tenía una credencial que en prod no existía, así que el workflow importó bien pero falla al ejecutarse. Por qué pasa: importar y ejecutar son dos momentos distintos; el import valida la estructura, no que las credenciales resuelvan al correr. Cómo detectarlo: si no abriste el workflow en prod para ver que sus nodos de credencial resuelven, no verificaste de verdad. Cómo corregirlo: después de importar, abre el workflow y confirma que cada nodo con credencial la muestra resuelta. "Import exitoso" no es "workflow funcional"; solo la verificación lo confirma.

Dejar que el workflow llegue activo y arranque sobre datos reales antes de verificar (práctico). Qué pasa: alguien fuerza la activación al importar (o activa apenas ve "import exitoso") y el workflow empieza a procesar pedidos reales de inmediato, con lo que traía —bug incluido, si lo había—. Por qué pasa: la prisa por "dejarlo corriendo" gana sobre el paso de verificar. Cómo detectarlo: si order-triage está procesando pedidos en prod antes de que abrieras el editor a revisarlo, encendiste a ciegas. Cómo corregirlo: aprovecha que el import trae el workflow inactivo por defecto. Verifica primero —credenciales, lógica—, activa después, a mano y mirando. El paso entre "llegó" y "corre" es tu última oportunidad de atrapar un problema antes de que toque un pedido real.

Tratar de "promover credenciales" desde el repo en cada cambio (conceptual y de seguridad). Qué pasa: alguien, buscando que la promoción sea "completa", intenta versionar las credenciales de prod en el repo e importarlas en cada ciclo con import:credentials. Termina o bien filtrando un secreto al repo, o bien complicando el flujo sin necesidad. Por qué pasa: confunde "promover el workflow" con "promover todo, credenciales incluidas". Cómo detectarlo: si tu flujo de promoción diario toca import:credentials desde un archivo del repo, mezclaste dos cosas que van separadas. Cómo corregirlo: el workflow se promueve en cada cambio; las credenciales se establecen una vez por entorno, al montarlo, y viven solo en la instancia (nunca en el repo). Separar los dos flujos es lo que mantiene tus secretos a salvo.

Ejercicios

Ejercicio 1 — Arma el comando de promoción. Sin correr nada, escribe el comando completo de import:workflow (en la forma Docker de la guía) para cada caso: (a) promover order-triage.json al contenedor n8n-prod, importándolo un archivo suelto; (b) promover una carpeta entera ./workflows con varios workflows al contenedor n8n-staging. Después explica en una frase por qué, en los dos casos, el workflow llega inactivo por defecto y por qué eso es deseable.

Ver solución

(a) docker exec -u node -it n8n-prod n8n import:workflow --input=/tmp/order-triage.json (asumiendo que copiaste el archivo al contenedor antes con docker cp, o que está en un volumen compartido). --input apunta a un archivo suelto.

(b) docker exec -u node -it n8n-staging n8n import:workflow --separate --input=/tmp/workflows — con --separate, --input apunta a una carpeta y se importan todos los .json de adentro. Es el espejo de --separate en export.

En los dos casos, el workflow llega inactivo porque --activeState vale false por defecto: importar no enciende nada. Es deseable porque te da una ventana para verificar —que las credenciales resuelven, que la lógica es la correcta— antes de activar a mano, en vez de que el workflow arranque sobre datos reales apenas llega.

Por qué funciona: armar el comando de memoria te obliga a distinguir el archivo suelto (--input=archivo.json) de la carpeta (--separate --input=carpeta), que es la misma distinción que ya tenías en export. Y razonar sobre --activeState te fija que la seguridad de la promoción está en el paso manual entre importar y activar.

Ejercicio 2 — Diagnostica una promoción rota en silencio. Un compañero te escribe: "Promoví order-triage a prod, el import dijo 'Successfully imported 1 workflow', lo activé, y ahora los pedidos entran pero fallan en el nodo del CRM con un error de autenticación. En staging funcionaba perfecto. ¿Qué pasó?" Explícale la causa más probable y cómo confirmarla y arreglarla.

Ver solución

La causa más probable es la trampa número uno: la credencial del CRM que order-triage referencia no resuelve en prod. El workflow trae un puntero a Cumbre CRM key; en staging ese puntero encontraba la credencial sandbox y funcionaba, pero en prod o no existe una credencial que resuelva ese puntero, o existe pero está vacía o mal configurada con el valor de producción. Por eso el import "funcionó" (validó la estructura) pero la ejecución falla al autenticarse: importar no comprueba que las credenciales resuelvan al correr.

Para confirmarlo: abre order-triage en el editor de prod y mira el nodo HTTP Request del CRM. Si la credencial aparece en rojo, "colgando" o sin asignar, ese es el problema. Para arreglarlo: crea o corrige en prod la credencial Cumbre CRM key con el token real del CRM de producción, asígnala al nodo, guarda, y vuelve a probar. Y para el futuro: verifica las credenciales antes de activar, no después de que fallen los pedidos.

Por qué funciona: este es el fallo más frecuente y más angustiante de la promoción, porque "el comando dijo éxito" da una falsa seguridad. Tener clara la diferencia entre "importó" y "funciona" —y que solo la verificación en el editor lo confirma— te ahorra procesar pedidos reales rotos y te deja diagnosticarlo en segundos cuando le pase a alguien de tu equipo.

Ejercicio 3 — Decide qué se promueve y qué no. Para cada elemento, di si viaja del entorno de origen al destino en una promoción diaria de order-triage, o si NO viaja (y por qué): (a) la lógica del workflow —nodos y conexiones—; (b) el token real del CRM de producción; (c) el estado "activo" del workflow; (d) el id del workflow.

Ver solución

(a) Viaja. La lógica —nodos, conexiones, configuración— es la receta, y es lo único que la promoción está pensada para mover. Va en el JSON que importas.

(b) NO viaja. El token real de producción nunca está en el JSON ni en el repo; vive solo en la instancia de prod, puesto una vez al montar el entorno. El JSON solo lleva un puntero a la credencial, no su valor. Que el secreto no viaje es lo que hace segura toda la promoción.

(c) NO viaja (por defecto). El workflow llega inactivo (--activeState es false por defecto); su estado de activación es una decisión que tomas en el destino, a mano, después de verificar. Que no viaje el "activo" es lo que evita encender producción a ciegas.

(d) Viaja, y es clave que lo haga. El id va en el JSON y coincide entre entornos, lo que hace que el import actualice el workflow existente en prod en vez de crear un duplicado. Un id estable es lo que sostiene el "un workflow, muchos entornos".

Por qué funciona: la promoción se entiende bien cuando distingues lo que es lógica común (viaja: la receta y su id) de lo que es configuración por entorno (no viaja: los secretos reales y el estado de activación). Esa separación —que empezaste a diseñar en el Módulo 3 y montaste en el Módulo 4— es exactamente lo que hace que promover sea seguro. Mover la receta sin mover los ingredientes de prueba a la cocina real.

Resumen y siguiente paso

En esta lección ejecutaste el eslabón promover del pipeline. Entendiste que promover es llevar una versión probada de un entorno al siguiente en una cadena de confianza —como ascender a un empleado por escalones—, y que no es solo correr un comando: es el comando envuelto en verificación, mapeo de credenciales y decisión de activación. Conociste import:workflow y sus banderas —--input, --separate, --activeState— como espejo del export:workflow que ya dominabas, y viste que el id del workflow hace que el import actualice en vez de duplicar. Enfrentaste las dos trampas de la promoción: las credenciales del destino (el JSON lleva un puntero, no el secreto, y la referencia tiene que resolver en prod con el valor real, gracias a las credenciales por entorno del Módulo 4) y la activación (el import trae el workflow inactivo por defecto, y tú lo enciendes a mano después de verificar). Viste el rol acotado de import:credentials —montar el entorno una vez, nunca promover secretos desde el repo—, la lista de verificación antes de promover a prod, y llevaste order-triage de staging a prod paso a paso: sacar del repo, verificar el diff, confirmar credenciales, importar inactivo, verificar, y encender con intención.

Antes de avanzar deberías poder: armar el comando de promoción para un archivo y para una carpeta; explicar por qué el JSON no lleva el secreto sino un puntero, y qué pasa si ese puntero no resuelve en el destino; decir por qué el workflow llega inactivo y por qué eso es bueno; y nombrar qué revisar antes de promover a prod.

La lección 3 es el control de calidad que va antes de cada promoción. Vas a aprender a revisar el cambio como un diff antes de que llegue a prod: el pull request como punto de revisión obligatorio, cómo leer el diff normalizado que la lección 2 te dejó impecable, y —el tema nuevo del módulo— cómo revisar workflows que una IA creó o modificó dentro de tu instancia. Porque la promoción segura no empieza con el comando: empieza con un humano que miró el diff y lo aprobó.

Recursos

• Use the command line — n8n Docs — la referencia oficial de import:workflow e import:credentials, todas sus banderas y la forma con docker exec. Es la fuente que confirmé para esta lección; corre --help en tu versión para verificar.
• Export and import workflows — n8n Docs — la vista de exportar e importar, base del movimiento de promoción.
• Manage credentials — n8n Docs — cómo n8n guarda y referencia las credenciales; el fundamento de por qué el JSON lleva un puntero y no el secreto.
• Set a custom encryption key — n8n Docs — la N8N_ENCRYPTION_KEY que cada entorno tiene por separado, necesaria si algún día importas un respaldo cifrado de credenciales.
• Workflow activation — n8n Docs — qué significa que un workflow esté activo; útil para entender la decisión de activar a mano después de importar.