Module 6: Promotion, Rollback, and Documented Delivery

2. Promoting workflows between environments

Next →

Description

By the end of this lesson you will be able to promote a workflow from one environment to the next with n8n's CLI: exporting it from the source and importing it into the destination with import:workflow, deciding whether it arrives active or inactive, and understanding why credentials are the delicate point of every promotion. You're going to meet import:credentials and its role at the destination, you're going to know what to check before promoting so you don't break production, and you're going to bring order-triage from staging to prod step by step, the way it's done in a real deployment.

This matters because promoting is the link turning your repository into something that really reaches production. Up to now you versioned, set up environments, and tested; all of that is worth little if the change tested in staging can't move to prod in a controlled way. And "in a controlled way" is the key: importing a workflow is a one-line command, but doing it without breaking Cumbre's real orders requires understanding what breaks when moving a workflow between instances —exactly the portability problem you studied in Modules 1 and 3— and how Module 4's per-environment credential separation solves it.

Connection to the module: lesson 1 showed you the complete pipeline; this one executes its second-to-last link, promoting. Here you use the import:workflow you barely glimpsed in Module 3 as "the way back," and you connect it with Module 4's per-environment credentials. Lesson 3 teaches you to review the diff before this promotion; lesson 5 teaches you to revert if the promotion goes wrong. So this lesson is the forward motion, and the ones around it are its quality control and its safety net. Pay attention to the activation decision and the credential mapping, because they're the two places a naive promotion breaks production silently.

What promoting is, and why it isn't just importing

Let's start by defining the word, because it gets used a lot and sometimes loosely.

Promoting a workflow means taking an already-tested version from one environment to another closer to production: from dev to staging, or from staging to prod. The word comes from the software development world, where a change "gets promoted" through a series of environments, earning its way to each one only after passing its tests. It isn't moving the workflow any old way; it's moving it forward in a chain of trust, where each link is more real and less forgiving than the last.

Think of it as a promotion at a company. A new employee doesn't arrive on day one running the critical operation. They start in a role where they can learn and get it wrong without serious consequences (dev), prove they perform in a more demanding but still supervised role (staging), and only once they've proven they hold up under pressure do they get promoted to the role where their mistakes really cost something (prod). Nobody gets promoted skipping the rungs, and nobody gets promoted without their performance being reviewed. Promoting a workflow is exactly that promotion: same "employee" —the workflow's logic— in a more responsible role.

Here's the nuance this lesson exists to install: promoting isn't just running import:workflow. The command is the mechanics —the promotion's paperwork— but the promotion is everything surrounding it: reviewing the change beforehand (lesson 3), mapping the destination's credentials, deciding whether the workflow arrives active, and having the rollback ready in case something fails (lesson 5). Someone who just runs the command is signing off on the promotion without reading the file. Let's read the file.

The anatomy of a promotion

Every promotion has the same shape, no matter which environments it happens between. It's three moves:

  1. Pull the good version from the source. Not any version: the one that already passed the tests. And in a professional flow, you don't pull it from staging's live instance, but from the repository, which is the source of truth. The JSON you're going to promote is the one committed in cumbre-automations, reviewed and approved.
  2. Put that version into the destination. With import:workflow, pointing at the destination environment's instance (prod). This is where the workflow "lands" in its new kitchen.
  3. Adjust what changes per environment. A workflow isn't just its logic; it also has credentials (which in prod are the real ones, not the test ones) and an activation state (should it start running as soon as it arrives, or stay inactive until someone turns it on?). These adjustments are the "promotion's paperwork" and are where a promotion breaks if not handled carefully.

Notice an underlying decision running through all three moves, one you already know from the "workflow as code" model: the logic travels, the configuration doesn't. The workflow's JSON —the nodes, the connections, how it's put together— is the same across the three environments: it's the recipe, and there's only one recipe. What changes between staging and prod isn't the recipe, it's the ingredients: in staging you use practice ingredients (test credentials, the sandbox CRM), in prod the real ones (Cumbre's real CRM). Promoting correctly means moving the recipe without accidentally moving the practice ingredients into the real kitchen.

import:workflow: putting the workflow into the destination

The promotion's central command is the mirror of the export:workflow you already master. Where export pulls workflows out of an instance into files, import puts files back into an instance. Its main flag is --input, the exact reflection of --output.

These are its flags, confirmed against n8n's official documentation as of July 2026. As always, run n8n import:workflow --help on your instance before trusting any of them: your version outranks this guide.

FlagWhat it does
--input=<path>Where to read from: a file (order-triage.json) or, with --separate, a folder.
--separateImports every .json file in the folder --input points to. The mirror of --separate on export.
--projectId=<id>Imports into a specific project on the destination instance. Doesn't combine with --userId.
--userId=<id>Imports assigning it to a specific user. Doesn't combine with --projectId.
--activeStateControls whether the workflow ends up active on import. Accepts false (default) or fromJson (multi-main mode only).
--skipMigrationChecksSkips version-migration validations. Use only if you know why you need it.
--helpPrints this list for your version.

Pay special attention to --activeState, because it holds one of the promotion's two traps. We'll get to it in a moment; first, the command's basic form.

To promote order-triage, you run import:workflow against the destination instance. If your environments run in Docker —this guide's case— each environment is its own container, so the docker exec points at prod's container:

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

Break it down with the eyes Module 3's lesson 2 already taught you to read these commands:

  • docker exec -u node -it n8n-prod — "run inside the production container, as user node, with a terminal." Notice the container's name: n8n-prod. This is where Module 4's isolation becomes concrete: there's one container per environment, and promoting to prod means pointing at that container, not staging's.
  • n8n import:workflow — the command, the mirror of export:workflow.
  • --input=order-triage.json — the file to import, which is the versioned, tested JSON you pulled from the repository.

An important detail that confuses people the first time: same as when exporting, the files import reads have to be where the command runs. If the command runs inside prod's container, order-triage.json has to be accessible in there —through a shared volume or copied in with docker cp beforehand. It's the same container-boundary logic from Module 3's lesson 2, now going the other direction.

Create versus update: what happens if the workflow already exists

Here's a subtlety deciding whether your promotion creates a new workflow in prod or updates the one already there. The rule, worth checking on your version because it touches the importer's fine behavior, is this: n8n uses the workflow's identifier (the JSON's id field) to decide. If a workflow with that same id already exists in prod, the import updates it —overwrites its logic with the file's. If none exists with that id, it creates it.

This is exactly what you want for promoting: the second time you promote order-triage to prod, you don't want a second, duplicate order-triage, you want the existing one to update to the new version. Having the id travel in the JSON and match across environments is what makes the promotion update instead of duplicate.

And here a circle closes that you opened in Module 1: remember Module 3's project warned against "duplicating workflows per environment." Now you see why it mattered. If each environment had its own copy with its own id, promoting would create endless duplicates. Since the logic gets versioned once, with a stable id, promoting always updates the correct version at the destination. One workflow, many environments.

Trap number one: the destination's credentials

This is the lesson's dangerous heart, and the point where a naive promotion breaks production in the worst way: silently, with no error given.

Remember from Module 1 what a workflow's JSON contains regarding credentials: it doesn't contain the secrets, it contains references. Every node needing a credential —the AI Agent node, the HTTP Request node to the CRM— saves a block like this in its JSON:

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

That block says "I use the credential with id aB3xK9, called Cumbre CRM key." It's a pointer, not the key. The real key —the CRM's token— lives encrypted in the instance's database, never in the JSON. That's what makes versioning the workflow safe: the secret isn't there.

But that pointer creates a problem when promoting. When you import order-triage into prod, the HTTP Request node arrives saying "I use credential aB3xK9." And now the critical question: does a credential exist in the prod instance that this pointer can resolve to?

  • If a credential exists in prod that the import can match to that reference —with the same id, or that Module 4's flow left aligned by name— the node uses it and the workflow works. And since in prod that credential contains Cumbre's real CRM token, the workflow talks to the real CRM. Perfect: that's what you want.
  • If nothing exists in prod resolving that reference, the node is left with a "hanging," unassigned credential. The workflow imported with no error —the command says "success"— but when running, the CRM node fails because it has nothing to authenticate with. And there's the silence: the promotion "worked," but the workflow is broken, and you don't find out until a real order tries to go through and can't.

This is where Module 4 saved you in advance. In that module you set up credentials per environment: each environment has its own credentials, with test ones in dev/staging and real ones in prod, but designed so the workflow's reference resolves in each. The clean strategy is for the credential to have the same name across all three environments —Cumbre CRM key— even though its content is different: in staging it points at the sandbox CRM, in prod at the real one. That way, the same order-triage.json works across all three, because on each instance the pointer finds a credential to resolve to, with the correct ingredient for that kitchen.

import:credentials: the role of credentials at the destination

The mirror command for credentials is import:credentials. It has almost the same flags as import:workflow —--input, --separate, --projectId, --userId— and it's used to put exported credentials into an instance.

But here a strong warning is needed, one carrying over all of Module 3's security discipline. In a professional flow, you don't promote prod's credentials by importing them from a repository file, because real credentials never live in the repository. That's this whole guide's security pillar: secrets don't get versioned. So, what is import:credentials for in a promotion?

Its legitimate use is the initial environment setup, not every change's cycle. When you bring up prod for the first time (Module 4), you have to populate it with its real credentials once. You can do it two honest ways:

  • By hand in the editor, creating each prod credential with its real value. It's the most transparent and recommended for a few credentials.
  • With import:credentials from a secure encrypted backup living outside the repository —like Module 3's project's ~/secure-backups/— and without --decrypted. Here the credentials file isn't in the repo; it's in your vault, and you only use it to populate the instance. For it to decrypt on import, the destination instance has to have the same N8N_ENCRYPTION_KEY it was encrypted with.

The rule worth locking in: the workflow gets promoted on every change; the credentials get set once per environment. Mixing the two —trying to "promote credentials" on every cycle from the repo— is the direct path to leaking a secret or breaking the security you took such care with. Daily promotion moves the logic; the credentials are already set in each environment since you set it up.

Trap number two: active or inactive on arrival

The second way to break prod with a promotion is subtle and has to do with timing. When you import a workflow, should it start running the moment it arrives, or stay inactive until you deliberately turn it on?

An active workflow is one that's listening and running: if order-triage is active in prod, its Webhook is receiving real orders and its logic is processing them. An inactive workflow is imported but asleep: it exists, but receives and processes nothing until someone activates it.

The decision matters because promoting to prod with the workflow arriving active right away is risky. Imagine you promote a version of order-triage that —without you noticing— has a bug. If it arrives active, it starts processing real orders immediately, with the bug, before you can verify anything. If instead it arrives inactive, you have a window to check everything's in place —credentials resolved, correct configuration— and then activate it deliberately, watching.

That's why import:workflow's default behavior is to bring the workflow in inactive: the --activeState flag defaults to false. It's a prudent n8n design decision: importing doesn't turn anything on; turning on is a separate, deliberate act. The fromJson value —which would say "activate according to what the JSON says"— only works in n8n's multi-main mode (an advanced scaling configuration this guide doesn't cover), so in practice, in your setup, imported workflows arrive inactive and you activate them when you're ready.

This is exactly what you want for a safe promotion. The prudent flow is: you import (arrives inactive) → you verify the credentials resolve and everything's in place → you activate by hand in prod's editor, watching. Never "import and let it start on its own." The workflow arrives, you review it, you turn it on. That small manual step between "arrived" and "is running" is one of the reasons CLI promotion is safe: it gives you a moment to breathe before real orders come in.

What to check before promoting to prod

Before running import:workflow against prod, a system owner goes through a checklist. It isn't bureaucracy: it's what stops you from breaking Cumbre's real orders. This is the list, and each point prevents a concrete disaster:

  • Did the change go through staging and its sandbox test? Never promote to prod something you didn't test first in a safer environment. It's the promotion principle: you earn the step, you don't skip it. (The test is Module 5.)
  • Did you review the diff of what you're promoting? You have to know exactly what changed compared to what's in prod today. A clean two-line diff is safe; a diff you don't understand is an alarm. (The review is lesson 3, the one that follows.)
  • Do the credentials the workflow references exist in prod, with real values? If the workflow uses Cumbre CRM key and Cumbre LLM key, confirm prod has those credentials populated with production secrets before promoting. If not, the workflow will import but fail to run.
  • Do you have the rollback ready? Before touching prod, know what the last good JSON is and how to go back to it. Never promote without knowing how to undo it. (Rollback is lesson 5.)
  • Are you going to import it inactive and activate by hand after verifying? Confirm you're not going to turn production on blind.

Notice the pattern: of the five points, three point at other lessons. That isn't accidental. Safe promotion is the whole module's cycle working together: you test (Module 5), you review (lesson 3), you promote (this lesson), and you have a way to revert (lesson 5). The import:workflow command is just the instant you pull the trigger; the safety is in everything you did before pulling it.

Worked example: promoting order-triage from staging to prod

Let's do the whole thing, with Cumbre. The scenario: in staging you tested a new version of order-triage —you added a threshold sending orders over 5000 pesos to manual review— the sandbox pass passed, and now you promote it to prod. We assume the guide's Docker scenario, with n8n-staging and n8n-prod containers.

Step 0 — Where you are. You're standing in the repository, with the versioned order-triage.json you already tested, and with prod running in its n8n-prod container with its real credentials already set up (since you set up the environment in Module 4).

cd cumbre-automations

What to expect: clean git status, git log showing the commit for the change you're going to promote. The version you're going to bring to prod is the one in workflows/order-triage.json, not whatever's "live" in staging. You pull from the source of truth, not the instance.

Step 1 — Check the diff (lesson 3 preview). Before moving anything, look at what changed compared to what's running in prod:

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

What to expect: thanks to Module 3's normalization, the diff shows only the real change's lines —the 5000 threshold and the manual review node— and no noise. If you saw changes you didn't expect, that's your stop signal: don't promote what you don't understand. (Lesson 3 goes deeper into reading this diff.)

Step 2 — Confirm the credentials in prod. Before importing, make sure prod has the credentials order-triage references. You can list them or just open prod's editor and verify Cumbre CRM key and Cumbre LLM key exist, populated with real values. This step is verification, not import: prod's credentials should already be there from setting up the environment.

What to expect: you confirm both credentials exist in prod with their production values. If one were missing, you create it now in prod's editor with its real value, before importing the workflow.

Step 3 — Get the JSON into prod's container. import reads from inside the container, so the file has to be accessible there. If your prod mounts a shared volume, copy the file into that folder; if not, use docker cp:

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

What to expect: order-triage.json is now inside the n8n-prod container, at /tmp/, ready for the import to read it.

Step 4 — Import into prod. The central command:

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

What to expect: the terminal confirms something like Successfully imported 1 workflow. In prod, the existing order-triage updated to the new version (because the id matched), and it arrived inactive (the default behavior). It isn't processing orders yet: it's imported and asleep, waiting for your verification.

Step 5 — Verify before turning it on. Open order-triage in prod's editor. Confirm two things: that the logic is the new one (the manual review node is there, the threshold is 5000) and that the nodes using credentials —the AI Agent and the HTTP Request— show their credentials resolved, not red or "hanging." If any node shows the credential unassigned, that's trap number one's problem: fix it before continuing.

What to expect: the workflow looks correct and its credentials resolve to prod's. Nothing is running yet.

Step 6 — Activate, deliberately. Only now, watching and with everything verified, you activate the workflow —with the activation switch in prod's editor.

What to expect: order-triage turns active in prod and starts processing real orders with the new logic. You just promoted a change to production in a controlled way: tested, reviewed, imported inactive, verified, and turned on on purpose. That small ritual is the difference between a deployment and an accident.

Stop for a second on what you didn't do: you didn't edit directly in prod, you didn't import the credentials from the repo, you didn't let the workflow start on its own before looking at it. Everything you didn't do is a way of breaking production you avoided on purpose.

Promoting the other direction: from dev to staging

Everything you saw applies equally to the earlier promotion, from dev to staging, with a difference in tone: staging forgives more than prod, because it doesn't process real orders. There you can be a bit less ceremonious —staging exists precisely for rehearsing— but the flow is the same: you pull the version from the repo, import it into staging's container, verify the test credentials resolve, and activate it to run Module 5's sandbox pass.

The general shape of any promotion, then, is a single one, and only the destination container changes:

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

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

Same command, different destination. What changes between the two isn't the import, it's how much care you put around it: toward prod, the full verification ritual; toward staging, a lighter version of the same. The more real environment deserves more ceremony.

Common mistakes

Promoting by pulling the workflow from the live instance instead of the repository (conceptual). What happens: someone, to promote, exports the workflow directly from staging's instance at that moment and imports it into prod, skipping the repository. If staging had a half-finished or uncommitted change, that dirty state travels to prod. Why it happens: "instance to instance" feels more direct than going through the repo. How to spot it: if what you're promoting doesn't match what's committed in the repository, you're promoting something unversioned. How to fix it: the repository is the source of truth. You promote what's committed and reviewed, not whatever happens to be in an instance. Pulling from the repo guarantees you promote exactly what you reviewed.

Importing and believing it "worked" because the command gave no error (practical, and the most silent one). What happens: you run import:workflow in prod, the terminal says Successfully imported, and you call the promotion done. But the CRM node had a credential that didn't exist in prod, so the workflow imported fine but fails when running. Why it happens: importing and running are two different moments; the import validates the structure, not that the credentials resolve when running. How to spot it: if you didn't open the workflow in prod to see its credential nodes resolve, you didn't truly verify it. How to fix it: after importing, open the workflow and confirm every node with a credential shows it resolved. "Successful import" isn't "functional workflow"; only verification confirms that.

Letting the workflow arrive active and start on real data before verifying (practical). What happens: someone forces activation on import (or activates as soon as they see "successful import") and the workflow starts processing real orders immediately, with whatever it carried —bug included, if there was one. Why it happens: the rush to "get it running" wins over the verification step. How to spot it: if order-triage is processing orders in prod before you opened the editor to review it, you turned it on blind. How to fix it: take advantage of import bringing the workflow inactive by default. Verify first —credentials, logic— activate afterward, by hand and watching. The step between "arrived" and "runs" is your last chance to catch a problem before it touches a real order.

Trying to "promote credentials" from the repo on every change (conceptual and security). What happens: someone, wanting the promotion to be "complete," tries to version prod's credentials in the repo and import them every cycle with import:credentials. They end up either leaking a secret into the repo, or unnecessarily complicating the flow. Why it happens: they confuse "promoting the workflow" with "promoting everything, credentials included." How to spot it: if your daily promotion flow touches import:credentials from a repo file, you mixed two things that go separately. How to fix it: the workflow gets promoted on every change; the credentials get set once per environment, when setting it up, and live only in the instance (never in the repo). Separating the two flows is what keeps your secrets safe.

Exercises

Exercise 1 — Build the promotion command. Without running anything, write the complete import:workflow command (in the guide's Docker form) for each case: (a) promoting order-triage.json to the n8n-prod container, importing a loose file; (b) promoting a whole ./workflows folder with several workflows to the n8n-staging container. Then explain in one sentence why, in both cases, the workflow arrives inactive by default and why that's desirable.

See solution

(a) docker exec -u node -it n8n-prod n8n import:workflow --input=/tmp/order-triage.json (assuming you copied the file into the container beforehand with docker cp, or it's on a shared volume). --input points at a loose file.

(b) docker exec -u node -it n8n-staging n8n import:workflow --separate --input=/tmp/workflows — with --separate, --input points at a folder and every .json inside gets imported. It's --separate's mirror on export.

In both cases, the workflow arrives inactive because --activeState is false by default: importing doesn't turn anything on. It's desirable because it gives you a window to verify —that credentials resolve, that the logic is correct— before activating by hand, instead of the workflow starting on real data the moment it arrives.

Why it works: building the command from memory forces you to distinguish the loose file (--input=file.json) from the folder (--separate --input=folder), which is the same distinction you already had on export. And reasoning about --activeState fixes for you that the promotion's safety is in the manual step between importing and activating.

Exercise 2 — Diagnose a silently broken promotion. A teammate writes: "I promoted order-triage to prod, the import said 'Successfully imported 1 workflow', I activated it, and now orders come in but fail at the CRM node with an authentication error. It worked perfectly in staging. What happened?" Explain the most likely cause and how to confirm and fix it.

See solution

The most likely cause is trap number one: the CRM credential order-triage references doesn't resolve in prod. The workflow carries a pointer to Cumbre CRM key; in staging that pointer found the sandbox credential and worked, but in prod either no credential exists resolving that pointer, or one exists but is empty or misconfigured with the production value. That's why the import "worked" (it validated the structure) but the run fails to authenticate: importing doesn't check that credentials resolve when running.

To confirm it: open order-triage in prod's editor and look at the CRM's HTTP Request node. If the credential shows red, "hanging," or unassigned, that's the problem. To fix it: create or fix the Cumbre CRM key credential in prod with the real production CRM token, assign it to the node, save, and test again. And for the future: verify credentials before activating, not after orders start failing.

Why it works: this is the promotion's most frequent and most distressing failure, because "the command said success" gives a false sense of security. Being clear on the difference between "imported" and "works" —and that only verification in the editor confirms it— saves you from processing broken real orders and lets you diagnose it in seconds when it happens to someone on your team.

Exercise 3 — Decide what gets promoted and what doesn't. For each element, say whether it travels from the source environment to the destination in a daily order-triage promotion, or whether it does NOT travel (and why): (a) the workflow's logic —nodes and connections; (b) the production CRM's real token; (c) the workflow's "active" state; (d) the workflow's id.

See solution

(a) Travels. The logic —nodes, connections, configuration— is the recipe, and it's the only thing promotion is meant to move. It goes in the JSON you import.

(b) Does NOT travel. The real production token is never in the JSON or the repo; it lives only in prod's instance, set once when setting up the environment. The JSON only carries a pointer to the credential, not its value. The secret not traveling is what makes the whole promotion safe.

(c) Does NOT travel (by default). The workflow arrives inactive (--activeState is false by default); its activation state is a decision you make at the destination, by hand, after verifying. Not having "active" travel is what prevents turning production on blind.

(d) Travels, and it's key that it does. The id goes in the JSON and matches across environments, which is what makes the import update the existing workflow in prod instead of creating a duplicate. A stable id is what sustains "one workflow, many environments."

Why it works: promotion is well understood once you distinguish what's shared logic (travels: the recipe and its id) from what's per-environment configuration (doesn't travel: the real secrets and the activation state). That separation —which you started designing in Module 3 and set up in Module 4— is exactly what makes promoting safe. Moving the recipe without moving the practice ingredients into the real kitchen.

Summary and next step

In this lesson you executed the pipeline's promote link. You understood that promoting means taking a tested version from one environment to the next in a chain of trust —like promoting an employee through the ranks— and that it isn't just running a command: it's the command wrapped in verification, credential mapping, and an activation decision. You met import:workflow and its flags —--input, --separate, --activeState— as the mirror of the export:workflow you already mastered, and saw that a workflow's id makes the import update instead of duplicate. You faced promotion's two traps: the destination's credentials (the JSON carries a pointer, not the secret, and the reference has to resolve in prod with the real value, thanks to Module 4's per-environment credentials) and activation (the import brings the workflow inactive by default, and you turn it on by hand after verifying). You saw import:credentials's limited role —setting up the environment once, never promoting secrets from the repo— the checklist before promoting to prod, and you brought order-triage from staging to prod step by step: pulling from the repo, checking the diff, confirming credentials, importing inactive, verifying, and turning it on deliberately.

Before moving on you should be able to: build the promotion command for a file and for a folder; explain why the JSON doesn't carry the secret but a pointer, and what happens if that pointer doesn't resolve at the destination; say why the workflow arrives inactive and why that's good; and name what to check before promoting to prod.

Lesson 3 is the quality control going before every promotion. You're going to learn to review the change as a diff before it reaches prod: the pull request as a mandatory review checkpoint, how to read the normalized diff lesson 2 left you impeccable, and —the module's new topic— how to review workflows an AI created or modified inside your instance. Because safe promotion doesn't start with the command: it starts with a human who looked at the diff and approved it.

Resources

← Previous1. Introduction: closing the delivery cycleNext →3. Reviewing changes as diffs, AI included