The Shadow Run: How I Test a New Workflow Version on Live Traffic Without Firing Side Effects

Description and use

Testing a new workflow version on live traffic without firing side effects using a shadow run in n8n: events are forked, side effects are stubbed and logged, divergences are queried and reviewed before promotion.

Problem

Ensuring a new workflow version behaves identically to the current production version on real traffic without causing unintended side effects.

Outcome

The shadow run detects side‑effect divergences that fixtures miss, preventing incidents like double‑emailing while keeping cost bounded by limiting the number of shadowed events.

Workflow

• 1. Trigger both live and shadow branches with the same event.
• 2. In the shadow branch, replace every effectful node with a stub that logs the intended effect instead of executing it.
• 3. Record side effect logs from both branches into live_log and shadow_log tables.
• 4. After a bounded number of events (e.g., 50), run a divergence query to classify differences as missing, extra, or changed.
• 5. Review all extra effects manually and sign off; ensure no missing effects; sample changed effects.
• 6. If all checks pass, promote v2 to production.
• 7. The shadow workflow deactivates itself after the event cap is reached to bound cost.

Evidence

Fixtures prove the mechanism works. They don't prove the new version behaves the same on real traffic. The shadow run does: it replays live events through the new workflow version with every side effect stubbed out, then diffs "what v1 did" against "what v2 would have done."

Source

The shadow stub must be incapable of firing the effect, not merely configured not to. I run my tag linter (previous post) against the shadow workflow before the run starts and assert: zero nodes tagged effectful.

Source

After N live events flow through (I use 50 -- enough to see the weird cases, cheap enough to afford), one query: ...

Source