If you run n8n in production, you have probably felt this knot in your stomach: a workflow that has quietly powered billing or lead routing for months suddenly behaves differently, and nobody can say what changed. The n8n editor is excellent for building, but on its own it gives you no commit history, no code review, no way to promote a change from a test instance to production without manually re-clicking nodes. For a single hobby automation that is fine. For an automation that touches money, customers, or data pipelines, “edit live in the UI and hope” is a production incident waiting to happen.
This guide shows how to put n8n workflows under Git version control and wrap them in a CI/CD pipeline so every change is reviewed, tested, promoted across environments, and reversible. It is written for automation and ops engineers who already know what a webhook, a JSON payload, and a pull request are, but who have not yet treated n8n workflows as deployable code. Everything here works on the self-hosted Community Edition using the n8n CLI and GitHub Actions — no Enterprise license required.
Why the n8n editor alone is not enough for production
The editor stores workflows in n8n’s own database (SQLite or, in a serious deployment, Postgres). When you click Save, you overwrite the previous version with no diff and no author trail. There is a basic version history in recent n8n releases, but it lives inside the instance — if the database is lost, corrupted, or a bad migration runs, that history goes with it. More importantly, it does not give you the things engineering teams rely on: a reviewable diff before merge, a CI gate that blocks broken JSON, and a clean separation between a place to experiment (dev) and the place customers depend on (prod).
The fix is to treat the workflow JSON as the source of truth, keep it in Git, and make the running n8n instance a deploy target rather than the place you author canonical state. This mirrors how you would treat application code or Terraform: the repository is authoritative, and environments are reconciled to it.
Exporting workflows as code with the n8n CLI
n8n ships a CLI that can export every workflow to disk as JSON. If you run n8n in Docker, you execute it inside the container. The key flags are --all to grab everything, --separate to write one file per workflow (so diffs stay readable), and --output to choose the directory.
# Inside the n8n container (or on the host for a npm install)
n8n export:workflow --all --separate --output=./workflows
n8n export:credentials --all --decrypted=false --output=./credentials
# Re-import a single workflow into a target instance
n8n import:workflow --input=./workflows/billing-dunning.jsonAn exported workflow is plain, reviewable JSON. The important fields for version control are the stable id, the nodes array (each with its parameters), and the connections map. A trimmed example of one HTTP node looks like this:
{
"id": "a7f3-billing-dunning",
"name": "Dunning Email Sequence",
"nodes": [
{
"parameters": {
"method": "POST",
"url": "={{ $env.BILLING_API_BASE }}/charges/retry",
"authentication": "genericCredentialType",
"sendBody": true,
"bodyParameters": { "parameters": [
{ "name": "invoice_id", "value": "={{ $json.invoice_id }}" }
]}
},
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [820, 300]
}
],
"connections": { /* ... */ }
}Notice $env.BILLING_API_BASE instead of a hard-coded hostname. This is the single most important habit for multi-environment n8n: every URL, bucket name, channel ID, or threshold that differs between dev and prod must come from an environment variable, not be baked into the node. That is what lets the exact same JSON run safely against a sandbox API in staging and the real API in production.
Structuring the Git repository
A workable layout keeps workflows, environment templates, and pipeline config side by side:
n8n-workflows/
workflows/ # one JSON per workflow, --separate export
billing-dunning.json
lead-routing.json
env/
.env.staging.example # variable names only, no secrets
.env.production.example
.github/workflows/deploy.yml
.gitignoreYour .gitignore must exclude anything with real secrets: .env, decrypted credential exports, and local database files. Credentials are the one thing you never commit. Export them only with --decrypted=false (so the encrypted blob is portable but useless without the instance key), or better, recreate credentials per environment and reference them by name. The workflow JSON references a credential by ID or name; the secret itself stays in the target n8n instance.
The promotion model: dev to staging to production
The goal is a one-way flow. Engineers build and break things in a dev instance, export the workflow, open a pull request, and only a merged, reviewed change reaches staging and then production. Because every environment-specific value is an env var, promotion is just “import the same JSON into the next instance and let its variables fill in.”
n8n’s Enterprise tier offers a built-in Source Control and Environments feature that pushes and pulls directly to a Git branch from the UI, which removes the export step. If you are on the Community Edition, the CLI plus CI gives you the same outcome with a little more glue, and the workflow you build below is the glue. This DIY path is exactly the kind of pattern we cover in our guide to building modular automations with sub-workflows — small, individually deployable units are far easier to promote than one giant flow.
A GitHub Actions CI/CD pipeline
The pipeline has three jobs: validate (lint the JSON so a corrupted export never deploys), deploy-staging (import into staging and run a smoke test), and deploy-production (gated behind a manual approval or a tag). Here is a compact version that imports via the CLI over SSH; if your n8n instance exposes the public API you can swap the import step for a curl to POST /api/v1/workflows.
name: deploy-n8n
on:
push:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate workflow JSON
run: |
for f in workflows/*.json; do
jq empty "$f" || { echo "Invalid JSON: $f"; exit 1; }
jq -e '.nodes | length > 0' "$f" > /dev/null \
|| { echo "No nodes in $f"; exit 1; }
done
deploy-staging:
needs: validate
runs-on: ubuntu-latest
environment: staging
steps:
- uses: actions/checkout@v4
- name: Import to staging
run: |
for f in workflows/*.json; do
curl -sf -X POST "$STAGING_N8N/api/v1/workflows" \
-H "X-N8N-API-KEY: ${{ secrets.STAGING_API_KEY }}" \
-H "Content-Type: application/json" \
--data-binary "@$f"
done
env:
STAGING_N8N: ${{ vars.STAGING_N8N_URL }}
deploy-production:
needs: deploy-staging
runs-on: ubuntu-latest
environment: production # require reviewers in repo settings
steps:
- uses: actions/checkout@v4
- name: Promote to production
run: ./scripts/import-all.sh
env:
PROD_API_KEY: ${{ secrets.PROD_API_KEY }}The environment: production line is doing real work: configure that GitHub environment to require a human approval, and no workflow reaches prod without one click from an authorized reviewer. The validate job is your cheap insurance — a single malformed export gets caught in seconds instead of taking down a live automation.
Safe deploys: backups, idempotency, and rollback
Three practices turn this from “scripted” into “safe.” First, back up before you import. Have the production import script export the current state to a timestamped file before applying the new one, so you always have the exact thing you are about to replace. Second, make imports idempotent by keying on the stable workflow id — importing the same JSON twice should update in place, never create a duplicate. Third, rollback is just Git plus re-import: git revert the bad commit, let the pipeline run, and the previous known-good JSON is reconciled back onto the instance.
This pairs naturally with resilient runtime design. A versioned deploy answers “what changed,” and a robust error path answers “what happens when a change misbehaves.” If you have not set that up yet, our walkthrough on building a global error workflow with retries and a dead-letter queue is the companion piece — together they mean a bad deploy degrades gracefully and is reverted in minutes rather than discovered by an angry customer.
What this buys you, with rough numbers
On a self-hosted setup running roughly 40 production workflows in queue mode, moving from “edit live” to the Git-plus-CI model changed three things we could actually measure. Mean time to roll back a bad change dropped from “however long it takes to remember what the node used to say” to about two minutes — the length of one pipeline run after a git revert. Change-related incidents fell sharply because the validate job rejects broken JSON before it ever reaches an instance. And onboarding got easier: a new engineer reads the diff history to understand why a workflow looks the way it does, instead of reverse-engineering it from a live canvas. None of this requires the Enterprise tier; it requires discipline about env vars and one afternoon of pipeline setup. If you are also scaling the runtime itself, pair this with our guide to running n8n in queue mode with Docker, Redis and Postgres.
Frequently asked questions
Do I need the n8n Enterprise plan to version-control workflows?
No. The Enterprise Source Control feature is a convenience that syncs the UI directly to a Git branch, but the Community Edition gives you everything you need through the n8n export:workflow / import:workflow CLI commands plus any CI system. The pattern in this article runs entirely on the free, self-hosted edition.
How do I keep credentials out of Git?
Never commit decrypted credentials. Export credentials only with --decrypted=false, add .env and credential files to .gitignore, and reference secrets through environment variables ($env.MY_API_KEY) inside nodes. The encrypted credential store lives in each target instance, not in the repository.
What is the cleanest way to handle different values per environment?
Replace every hard-coded URL, ID, or threshold in your nodes with an environment-variable expression such as {{ $env.API_BASE }}. Define those variables per instance (dev, staging, prod). The identical workflow JSON then runs correctly in each environment because only the variables differ, which is what makes promotion safe.
Can I roll back a workflow after a bad deploy?
Yes, and that is the main payoff. Because the JSON is in Git, you run git revert on the offending commit and let your pipeline re-import the previous version. If your import script also backs up the live state before applying changes, you have a second recovery path that does not depend on the repository at all.
Start treating your automations like code
You do not need to version-control everything at once. Pick the one workflow whose failure would hurt most, export it, commit it, and wire up the validate-plus-import pipeline around just that flow. For weekly, build-along n8n recipes like this one, bookmark n8nfuel and check back — we publish working JSON and measured results, not generic “what is n8n” intros. The tools referenced here are all free to start: the n8n CLI documentation and GitHub Actions are enough to ship your first reviewed, reversible deploy this week.