n8n-gitops

A GitOps CLI tool for n8n Community Edition that brings version control and collaborative workflow development to n8n.

n8n is a fair-code workflow automation platform (like Zapier/Make.com but self-hosted) that connects 400+ services and apps. n8n-gitops adds the GitOps deployment pipeline that is missing from both the Community Edition and the official n8n-cli lightweight API client.

Features

• 🔄 Mirror Mode Export: Always keeps local repository in perfect sync with n8n
• 📦 Code Externalization: Store Python/JavaScript code in separate files
• 🔑 Credential Documentation: Auto-generate documentation of workflow credential dependencies
• 🏷️ Git-Based Deployment: Deploy specific tags/branches/commits
• ✅ Validation: Validate workflows and manifests before deployment
• 🔌 Active State Management: Control workflow activation via API endpoints
• 🧹 Clean Deployments: Replace workflows with clean state

Quick Start

# Install with uv (recommended — isolated, no sudo)
uv tool install n8n-gitops

# Or with pipx (Ubuntu/Debian/Fedora/macOS)
pipx install n8n-gitops

# Or with pip (user install, no sudo)
pip install --user n8n-gitops

# Create project
n8n-gitops create-project my-n8n-project
cd my-n8n-project

# Configure authentication
n8n-gitops configure --config dev \
  --api-url https://your-n8n-instance.com \
  --api-key your-api-key-here

# Export workflows
n8n-gitops export

# Commit to Git
git init
git add .
git commit -m "Initial export"
git tag v1.0.0

# Deploy
n8n-gitops deploy --git-ref v1.0.0

Core Guides

• Getting Started - Installation and quick start
• Authentication - Configure API credentials
• Export - Mirror workflows from n8n
• Deployment - Deploy workflows to n8n
• Git Hooks - Automate export and deploy via git hooks
• Code Externalization - Store code in separate files
• Manifest File - Workflow configuration format
• n8n-cli Comparison - Differences between n8n-gitops and the official n8n-cli
• n8n Enterprise Git Comparison - Decide between n8n-gitops and Enterprise Git
• Commands Reference - All CLI commands
• GitOps Principles - How n8n-gitops aligns with GitOps principles

Key Concepts

Mirror Mode

Export always mirrors your n8n instance:

n8n-gitops export

• ✅ Exports ALL workflows
• 🗑️ Deletes local workflows not in n8n
• 🗑️ Deletes orphaned script files
• 📝 Updates manifest to match remote

Code Externalization

Store code in separate files instead of inline JSON (controlled by externalize_code in n8n/manifests/workflows.yaml, default: true):

Workflow JSON:

{
  "parameters": {
    "pythonCode": "@@n8n-gitops:include scripts/my-workflow/process.py"
  }
}

Script File:

def process(data):
    return data.upper()

result = process(input)

Git-Based Deployment

Deploy from any Git reference:

# Deploy from tag
n8n-gitops deploy --git-ref v1.0.0

# Deploy from branch
n8n-gitops deploy --git-ref main

# Deploy from commit
n8n-gitops deploy --git-ref abc123

Commands

# Create project structure
n8n-gitops create-project <path>

# Install git hooks (export on commit, deploy on pull)
n8n-gitops install-hooks [--config NAME] [--api-url URL] [--api-key KEY]

# Export workflows (mirror mode)
n8n-gitops export

# Validate workflows
n8n-gitops validate [--strict]

# Deploy workflows
n8n-gitops deploy [--git-ref REF] [--dry-run] [--prune]

# Rollback to previous version
n8n-gitops rollback --git-ref <ref>

See Commands Reference for complete documentation.

Example Workflow

# 1. Export from n8n
n8n-gitops export

# 2. Edit scripts
vim n8n/scripts/payment-processing/validate.py

# 3. Validate changes
n8n-gitops validate --strict

# 4. Commit to Git
git add .
git commit -m "Improve payment validation"
git tag v1.1.0

# 5. Deploy
n8n-gitops deploy --git-ref v1.1.0

Project Structure

my-n8n-project/
├── n8n/
│   ├── workflows/           # Workflow JSON files
│   ├── scripts/             # Externalized code
│   │   └── my-workflow/
│   │       ├── process.py
│   │       └── transform.js
│   ├── credentials.yaml     # Credential documentation (auto-generated)
│   └── manifests/
│       ├── workflows.yaml   # Workflow manifest
│       └── env.schema.json  # Environment schema
└── .gitignore

Development

# Clone the repository
git clone https://github.com/n8n-gitops/n8n-gitops.git
cd n8n-gitops

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

# Run tests
uv run pytest -v  # with uv
# or
pytest -v  # with pip

Requirements

• Python 3.10+
• Git
• n8n instance with API access

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.