n8n-sync — Git-based version control for n8n Community Edition workflows

#automation #cli #devops #git

If you are self-hosting n8n Community Edition, you already know the pain: no built-in version control. Enterprise has Source Control at €667/mo, but for Community users, there is nothing.

I got tired of manually exporting workflow JSON, committing it, and fixing credentials by hand when promoting from staging to production. So I built n8n-sync — a CLI that gives you Git-friendly version control for your n8n workflows.

Install

pip install n8n-sync

Quick start

n8n-sync init          # interactive setup
n8n-sync pull          # export workflows to normalized files
git add workflows && git commit -m snapshot
n8n-sync diff --check  # CI-ready: exits 1 on drift, 0 if in-sync
n8n-sync push --dry-run  # preview changes
n8n-sync push             # apply to remote

Commands

Command	Description
`n8n-sync init`	Interactive setup — creates config file
`n8n-sync pull`	Export all workflows to normalized JSON files
`n8n-sync push`	Create/update workflows on remote instance
`n8n-sync diff`	Show semantic differences between local and remote
`n8n-sync status`	List all workflows with drift detection
`n8n-sync list`	Show remote workflows with IDs, names, active state

Why n8n-sync?

Without version control, self-hosted n8n workflows are a black box:

❌ No history of changes
❌ No way to review workflow modifications before they go live
❌ No CI/CD integration
❌ Credentials break when copying between instances
❌ Cannot rollback a broken workflow

n8n-sync fixes all of this:

✅ Readable Git diffs — YAML frontmatter + sorted JSON
✅ Credential mapping — staging → production without manual fixes
✅ CI integration — diff --check exits 1 on drift
✅ Drift detection — know if someone changed a workflow in the UI
✅ Dry-run push — preview before applying
✅ No Enterprise required — works with any Community Edition instance
✅ .env file support — keep API keys out of your shell history

CI/CD integration

Use diff --check in your GitHub Actions pipeline:

name: n8n workflow drift check
on: [push, pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install n8n-sync
      - run: n8n-sync diff --instance production --check
        env:
          N8N_PRODUCTION_KEY: ${{ secrets.N8N_PRODUCTION_KEY }}

PyPI: https://pypi.org/project/n8n-sync/
GitHub: https://github.com/badwalx/n8n-sync

Would love feedback from other self-hosters. What is missing? What would make this useful for your workflow?

DEV Community