Sync, backup, import and organise n8n workflows and folders.
Installation · Getting Started · Configuration · Features · Contributing · Troubleshooting
Keep workflows, credentials, and folders in sync with GitHub, GitLab, or a local file system for quick import, backup, versioning, and fast organisation. The CLI wraps n8n's REST API to enable folder management so you can maintain consistent organisation between environments.
| Command | Action |
|---|---|
| Push | Exports workflows, credentials, and/or environment variables from the n8n instance, maintains folder structure, and pushes to Git or a local folder. |
| Pull | Pulls workflows from a local path or Git repo and imports them into n8n, preserving repository structure. |
| Reset | Replays repository history into your n8n workspace (by commit/tag/time window) to restore, archive, or remove workflows with interactive or scripted flows. |
n8n-git supports multiple execution environments:
-
Docker Execution (Default):
- Self-hosted n8n instance running in Docker
- Docker installed and accessible on your host machine
-
Local Execution:
- n8n installed locally (npm/pnpm)
n8ncommand available in PATH
-
Embedded Execution:
- n8n-git installed inside your n8n container
- Useful for triggering git operations from n8n workflows
Common Requirements:
- Host system with
bash4+,git,curl, andjq - Git repository access (GitHub/GitLab) or local filesystem access
Note: n8n-git is designed for self-hosted n8n instances running in Docker containers. It does not currently support n8n Cloud.
curl -sSL https://raw.githubusercontent.com/tcoretech/n8n-git/main/install.sh | sudo bashThis installs n8n-git to /usr/local/bin and libraries to /usr/local/share/n8n-git/lib. Customize with environment variables:
PREFIX="$HOME/.local" curl -sSL https://raw.githubusercontent.com/tcoretech/n8n-git/main/install.sh | bashgit clone https://github.com/tcoretech/n8n-git.git
cd n8n-git
make install # Defaults to /usr/local; override with PREFIX=/custom/pathVerify installation: n8n-git --help
Configuration follows this precedence chain:
- CLI arguments (highest priority)
- Local
.config(project directory) - User config (
~/.config/n8n-git/config) - Interactive prompts (if no value found)
- Defaults (built-in fallbacks)
Run the interactive config wizard:
n8n-git configThis creates ~/.config/n8n-git/config with your settings.
Important: Folder structure sync requires n8n REST API authentication. The n8n API does not yet expose folder management via API keys, so session-based authentication is currently required.
Create a Basic Auth credential in n8n:
-
In n8n UI: Credentials → Add Credential → Basic Auth
-
Enter your n8n login email and password
-
Name it
N8N REST BACKUP(or your preferred name) -
Add to your config file:
N8N_LOGIN_CREDENTIAL_NAME="N8N REST BACKUP" N8N_BASE_URL="http://localhost:5678" FOLDER_STRUCTURE=true
Note on API Keys: While
N8N_API_KEYis supported in the config, it's currently a placeholder awaiting n8n API support for folder operations. Session authentication is the working method. Folder structure is optional: Without it, workflows are stored flat by ID/name. Enable it to preserveProject/Folder/Workflow.jsonhierarchy in Git.
Backup workflows to Git (with folder structure):
n8n-git push --repo <username>/n8n-backup --github-path backup-folder/Pull workflows from a public repository into a specific n8n path:
n8n-git pull \
--repo Zie619/n8n-workflows \
--github-path workflows/Gmail \
--n8n-path Examples/GmailExplore interactive reset (time travel through Git history):
n8n-git reset --interactiveThis lets you browse commits and restore your workspace to any point. Use --mode soft to archive workflows or --mode hard to delete them permanently.
Undo the pull (reset back to before):
n8n-git reset --interactive --mode soft
# Select the commit before your pull operationFor your default settings, use the interactive wizard:
n8n-git config # Creates/updates ~/.config/n8n-git/configThis sets up your user-wide configuration at ~/.config/n8n-git/config.
For different use cases (production backup, client sync, development testing), create project-specific configs:
# Example: Production daily backup
mkdir -p ~/projects/n8n-production-backup
cp .config.example ~/projects/n8n-production-backup/.config
cd ~/projects/n8n-production-backup
# Edit for your use case:
cat > .config <<EOF
GITHUB_REPO="mycompany/n8n-prod-backup"
GITHUB_BRANCH="main"
WORKFLOWS=2 # Remote Git storage
CREDENTIALS=1 # Local encrypted storage
FOLDER_STRUCTURE=true
N8N_CONTAINER="n8n-prod"
EOF
# Run from this directory - uses local .config
n8n-git push| Config Variable | CLI Flag | Description | Values |
|---|---|---|---|
| Git options | |||
GIT_HOST |
--git-host <domain> |
Git host (e.g. gitlab.com) | github.com (default) |
GIT_REPO |
--repo <user/repo> |
Git repository | myuser/n8n-backups |
GIT_TOKEN |
--token <pat> |
Git Personal Access Token | ghp_... |
GIT_BRANCH |
--branch <name> |
Git branch | main (default) |
GITHUB_PATH |
--github-path <path> |
Repo subdirectory (supports %DATE%, %PROJECT%, %PERSONAL_PROJECT%, %HOSTNAME%) |
backups/%DATE%/ |
| n8n Instance Options | |||
N8N_CONTAINER |
--container <id|name> |
Docker container | n8n (default) |
N8N_BASE_URL |
--n8n-url <url> |
n8n base URL | http://localhost:5678 |
N8N_API_KEY |
--n8n-api-key <key> |
n8n API key (placeholder) | n8n_api_... |
N8N_LOGIN_CREDENTIAL_NAME |
--n8n-cred <name> |
Session auth credential | N8N REST BACKUP |
N8N_EMAIL |
--n8n-email <email> |
Direct session email | Not recommended |
N8N_PASSWORD |
--n8n-password <pass> |
Direct session password | Not recommended |
N8N_PROJECT |
--project <project> |
n8n Project | %PERSONAL_PROJECT% (default) |
N8N_PATH |
--n8n-path <path> |
Path within n8n project | clients/acme |
| Storage Mode Options | |||
WORKFLOWS |
--workflows <mode> |
Workflow handling | 0=skip, 1=local, 2=Git |
CREDENTIALS |
--credentials <mode> |
Credential handling | 0=skip, 1=local, 2=Git |
ENVIRONMENT |
--environment <mode> |
Environment variable handling | 0=skip, 1=local, 2=Git |
LOCAL_BACKUP_PATH |
--local-path <path> |
Local storage directory | ~/n8n-backup |
DECRYPT_CREDENTIALS |
--decrypt <true|false> |
Export decrypted credentials | false (default) |
| Folder Structure Options | |||
FOLDER_STRUCTURE |
--folder-structure |
Sync n8n folder hierarchy | true/false |
| General Options | |||
DRY_RUN |
--dry-run |
Simulate without changes | Flag / true/false |
ASSUME-DEFAULTS |
--defaults |
Non-interactive mode | Flag / true/false |
VERBOSE |
--verbose |
Verbose logging | Flag / true/false |
LOG_FILE |
--log-file <path> |
Log to file | Path |
| N/A | --config <path> |
Custom config file | Path |
Full reference: See .config.example for all options with inline documentation.
Security Best Practice: Never set CREDENTIALS=2 (remote Git) and DECRYPT_CREDENTIALS=true at the same time — this would commit plaintext secrets to Git!
Export workflows, credentials, and environment variables from n8n to Git or local storage.
Examples:
Git backup with folder structure — Ideal for version control and team collaboration. Workflows are pushed to Git while sensitive credentials remain local and encrypted.
n8n-git push \
--container n8n \
--workflows 2 \
--credentials 2 \
--folder-structure \
--n8n-url "http://localhost:5678"Local-only backup — Best for air-gapped environments or when you want full control over storage. All data stays on your local machine without touching remote repositories.
n8n-git push \
--container n8n \
--workflows local \
--credentials local \
--environment localAutomated daily backup via cron — Perfect for scheduled production backups. Runs automatically at 2 AM daily with dated folders for easy restoration. Use --defaults for non-interactive execution.
# /etc/cron.d/n8n-backup
0 2 * * * user /usr/local/bin/n8n-git push \
--workflows 2 \
--credentials 1 \
--folder-structure \
--github-path "daily-backup/%DATE%/" \
--defaultsKey Flags:
--workflows 0|1|2— Skip, local, or Git storage--credentials 0|1|2— Credential handling mode--environment 0|1|2— Environment variable handling--folder-structure— Preserve n8n folder hierarchy--decrypt true|false— Export plaintext credentials (dangerous!)--github-path <prefix>— Set Git subdirectory (supports%DATE%,%PROJECT%)--dry-run— Preview without making changes--defaults— Skip prompts (for automation)
Import workflows from Git or local storage into n8n. Optionally recreate folder structure.
Examples:
Restore from Git with folder structure — Ideal for disaster recovery or cloning n8n instances. Recreates the complete project and folder hierarchy from your backup repository.
n8n-git pull \
--container n8n \
--repo "user/n8n-backup" \
--folder-structure \
--n8n-url "http://localhost:5678" \
--defaultsImport from local backup — Best for offline restores or when working without Git. Imports workflows and credentials from local filesystem storage without folder sync.
n8n-git pull \
--container n8n \
--workflows local \
--credentials localSelective restore with ID preservation — Perfect for importing specific workflows without duplicates. Restores only workflows while preserving their original IDs to avoid conflicts with existing workflows.
n8n-git pull \
--repo "user/n8n-backup" \
--workflows 2 \
--credentials 0 \
--preserve \
--defaultsKey Flags:
--workflows 0|1|2— Source: skip, local, or Git--credentials 0|1|2— Import credentials--folder-structure— Recreate n8n folders from Git structure--preserve— Keep original workflow IDs (avoid duplicates)--no-overwrite— Assign new IDs to prevent conflicts--defaults— Use config defaults, skip prompts
Pull Pipeline:
- Staging — Generate manifest of workflows from Git/local
- Folder State — Load n8n project/folder hierarchy
- Folder Sync — Create missing folders recursively
- Folder Assignment — Map workflows to correct folders
- Validation — Verify import success, report metrics
Replay Git history into n8n to restore, archive, or delete workflows based on commits, tags, or time windows.
Examples:
Reset to specific commit — Useful for undoing recent changes or reverting to a known good state. Soft mode archives workflows that don't exist in the target commit.
n8n-git reset --to abc123f --mode softInteractive commit browser — Best for exploring history visually. Browse commits with filters and toggle between day/week view to find the exact state you want.
n8n-git reset --interactive --mode softTime-window recovery — Perfect for recovering workflows from a specific date range. Restores all workflows that existed during the specified time period.
n8n-git reset \
--since "2025-11-01 09:00" \
--until "2025-11-04 23:59" \
--mode softHard reset to tag — Use with caution for permanent cleanup. Permanently deletes workflows not present in the target commit (after archiving them first).
n8n-git reset --to v2.0.0 --mode hard # Use with caution!Preview impact without changes — Always preview first to understand what will change. Shows which workflows would be archived or deleted without actually performing the operation.
n8n-git reset --to main --dry-runKey Flags:
--to <sha|tag>— Target commit/tag/branch--since <time>/--until <time>— Time window (natural language supported)--interactive— Visual commit picker with filters--mode soft|hard— Soft=archive, Hard=delete--dry-run— Preview plan without execution
Reset Modes:
| Mode | Behavior | API Calls |
|---|---|---|
soft |
Archive workflows missing from target | POST /rest/workflows/{id}/archive |
hard |
Delete workflows not in target (after archive) | Archive + DELETE /rest/workflows/{id} |
Full documentation: docs/reset.md
-
Storage Modes:
0/disabled— Skip component1/local— Store in~/n8n-backup(encrypted, air-gapped)2/remote— Push to Git repository
-
Sparse Checkout — Efficient Git operations with
--github-path(only fetch relevant subdirectory) -
Per-Workflow Commits — Individual commits per workflow with
[new]/[updated]/[deleted]messages -
JSON Prettification — Automatic formatting (2-space indent, sorted keys) for readable diffs
-
Permission Enforcement — Local credentials stored with
600permissions (user-only access) -
Alpine & Debian Support — Compatible with both n8n container base images
-
Dry-Run Mode — Preview all operations without side effects (
--dry-run) -
Verbose Logging — Detailed output for debugging (
--verbose)
If n8n-git saves you time or helps you in your workflows,
you can say thanks and support further development here:
-
Clone and setup:
git clone https://github.com/tcoretech/n8n-git.git cd n8n-git -
Run linting:
make lint # Runs ShellCheck + bash syntax validation -
Run tests:
make test # Full regression suite (syntax + push/pull/reset tests)
-
Create release package:
make package # Stages dist/n8n-git/ for distribution
lib/
├── utils/
│ ├── common.sh # Logging, config, Docker helpers
│ └── interactive.sh # Interactive prompts & wizards
├── n8n/
│ ├── n8n-api.sh # REST API interactions (auth, folders)
│ └── decrypt.sh # Credential decryption
├── push/
│ ├── export.sh # Push orchestration
│ ├── folder_mapping.sh # Folder hierarchy organization
│ └── container_io.sh # Docker I/O operations
├── pull/
│ ├── import.sh # Pull orchestration
│ ├── staging.sh # Manifest generation
│ ├── folder-state.sh # n8n state caching
│ ├── folder-sync.sh # Folder creation
│ ├── folder-assignment.sh # Workflow-to-folder mapping
│ ├── validate.sh # Post-import validation
│ └── utils.sh # Pull helpers
├── github/
│ ├── git.sh # Git operations
│ └── git_ops.sh # Commit message generation
└── reset/
├── reset.sh # Reset orchestration
├── plan.sh # Diff calculation
├── apply.sh # Workflow archive/delete/restore
├── resolve.sh # Target resolution
├── time_window.sh # Time-based commit lookup
└── common.sh # Reset utilities- Strict mode: All scripts use
set -Eeuo pipefail - Logging: Use
log LEVEL "message"(INFO/WARN/ERROR/SUCCESS/DEBUG/DRYRUN/HEADER) - Module boundaries: See docs/ARCHITECTURE.md
- Tests: Must pass
make testbefore committing - CI: 5-job pipeline validates syntax, linting, push, pull, reset
- Read docs/ARCHITECTURE.md for system design
- Follow existing patterns in
lib/utils/common.sh - Use
dockExecfor Docker operations (respects dry-run) - Test locally:
tests/test-shellcheck.sh,tests/test-syntax.sh - Keep changes focused and maintainable
Problem: "n8n API validation failed" or "Unable to prepare n8n API authentication"
Solutions:
-
Verify
N8N_BASE_URLis reachable:curl -I http://localhost:5678
-
Check credential name matches exactly:
# In n8n UI: Settings → Credentials → Find your Basic Auth credential # Update config: N8N_LOGIN_CREDENTIAL_NAME="exact-name-here"
-
Test API access manually:
# With API key: curl -H "X-N8N-API-KEY: your_key" http://localhost:5678/api/v1/workflows?limit=1 # Or use n8n-git diagnostic: n8n-git push --dry-run --verbose
-
Ensure n8n container is running:
docker ps | grep n8n
Problem: Pull creates duplicate workflows instead of updating existing ones
Solutions:
- Use
--preserveto keep original IDs from Git - Use
--no-overwriteto force new IDs (creates duplicates intentionally) - Check for ID collisions in workspace before pulling
- Review with dry-run first:
n8n-git pull --dry-run --verbose
Problem: "Not valid JSON" errors during push or pull
Solutions:
-
Malformed workflow JSON: Export individually and check syntax:
docker exec my-n8n n8n export:workflow --id=123 --output=/tmp/test.json docker exec my-n8n cat /tmp/test.json | jq empty
-
UTF-8 BOM: n8n-git auto-strips BOM, but verify manually:
file <workflow.json> # Should say "UTF-8" not "UTF-8 Unicode (with BOM)"
-
Trailing commas: Check JSON with:
jq empty <file.json> -
Container encoding issues: Ensure
LANG=en_US.UTF-8in n8n container
Problem: "Failed to push" or "GitHub access denied"
Solutions:
-
Verify PAT permissions: Token needs
reposcope (full control) -
Test Git access:
git ls-remote https://ghp_TOKEN@github.com/user/repo.git
-
Check repository exists: Visit
https://github.com/user/repo -
Firewall/proxy: Test HTTPS connectivity:
curl -I https://github.com
-
Token in config: Verify
GITHUB_TOKENis set and not quoted incorrectly
Problem: "Permission denied" on local storage directories
Solutions:
# Fix local backup directory permissions:
chmod 700 ~/n8n-backup
chmod 600 ~/n8n-backup/**/*.json
# Fix config permissions:
chmod 600 ~/.config/n8n-git/config
# Run with correct user:
# If installed with sudo, either:
# - Run as root: sudo n8n-git push
# - Or reinstall as user: PREFIX=$HOME/.local make install# Enable verbose output:
n8n-git push --verbose
# Enable trace (prints every command):
n8n-git push --trace
# Dry-run to preview without changes:
n8n-git push --dry-run
# Check installation:
n8n-git --help
which n8n-git
ls -la /usr/local/share/n8n-git/lib/
# Verify container connectivity:
docker exec my-n8n n8n --version
# Check Git configuration:
git config --global user.name
git config --global user.email- Run with
--verbose --dry-runto see detailed execution - Check logs:
~/n8n-backup/logs/or custom--log-filepath - Review docs/ARCHITECTURE.md for system internals
- Open an issue with:
- Command run (redact secrets!)
- Full output with
--verbose - n8n version, OS, Docker version
- Contents of
.config(redact tokens!)
- Architecture Documentation — System design, module boundaries, authentication flows
- Reset Guide — Complete reset feature documentation
- Configuration Reference — All config options with examples
- Changelog — Release history and breaking changes
MIT License — Free to use, modify, and distribute.
