n8n Cross-Environment Migration: Credentials and Variables

TL;DR

• n8n exports omit encrypted credentials; cross-instance imports result in empty credential fields
• Environment variable references ({{ $env.VAR_NAME }}) export as empty placeholders without value expansion
• GitOps + n8n CLI commands enable version-controlled workflow management
• Separating credentials from workflow JSON and using JSON Schema validation prevents migration errors
• The OWNER_ADDED event hook can automate workflow permission synchronization across environments

Summary

Our team deployed n8n in Q4 2023 to handle approximately 12,000 daily cross-system automation tasks—ranging from CRM lead syncing to logistics status updates. What started as a small deployment for 3 users quickly scaled to 15 team members across 4 business lines. This growth exposed critical gaps in n8n’s export/import mechanism: credentials are encrypted separately using instance-specific keys, and environment variable references do not carry their runtime values during export.

The most severe incident occurred when an operator imported production workflows into a staging environment. A workflow processing 800 daily orders had all HTTP Request node credentials replaced with <string> placeholders, leaving the business undetected for two days.

The root cause stems from three interacting constraints: credential encryption isolation tied to the source instance’s key, environment variable interpolation occurring only at runtime, and team permission transfer during migrations. Simply exporting and importing JSON files proves unreliable because the same workflow file renders credentials correctly on the source instance but displays empty fields on any other instance.

Our solution implements GitOps principles using n8n’s CLI commands. The n8n-workflow-export.sh script exports workflows separately from credentials, forcing .nodes[].credentials = {} during export to strip encrypted data while preserving credential type references. Credentials themselves receive separate handling, encrypted with GPG before Git commit. Before any export, operators must confirm variable expansion in the source instance—either through UI testing or a pipeline expansion step. The OWNER_ADDED event hook handles automatic permission synchronization during imports.

Key Takeaways

If you export workflows for migration, always separate credentials from workflow JSON and re-bind them in the target environment.

If you use environment variable references in node parameters, expand them before exporting to avoid empty field issues.

If you manage workflows across environments, commit workflow JSON to Git with credentials encrypted separately.

If you onboard team members to existing workflows, use the OWNER_ADDED event hook to automate permission assignment.

If you want reliable cross-instance workflow portability, treat n8n’s export as the start of a structured deployment process, not a standalone solution.

Read the Full Article (Chinese)

This is an abstract. The full technical walkthrough with the complete n8n-workflow-export.sh script, docker-compose override configuration, and detailed troubleshooting steps is available in Chinese.