Skip to main content

Getting Started

Installation​

pip install -e .

Or for development:

pip install -e ".[dev]"

Quick Start​

1. Create a new project​

n8n-gitops create-project my-n8n-project
cd my-n8n-project

This creates the following structure:

my-n8n-project/
├── n8n/
│   ├── workflows/
│   ├── manifests/
│   │   ├── workflows.yaml
│   │   └── env.schema.json
│   └── scripts/
├── .gitignore
└── .n8n-auth.example

2. Configure authentication​

Copy the example auth file and add your n8n API credentials:

cp .n8n-auth.example .n8n-auth

Edit .n8n-auth:

N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-api-key-here

Alternatively, use environment variables:

export N8N_API_URL=https://your-n8n-instance.com
export N8N_API_KEY=your-api-key-here

See Authentication for more details.

3. Export existing workflows​

# Export workflows (uses externalize_code from manifest, default: true)
n8n-gitops export

This creates:

  • JSON files in n8n/workflows/
  • Manifest entries in n8n/manifests/workflows.yaml
  • When externalize_code is true in n8n/manifests/workflows.yaml (default): Script files in n8n/scripts/ with include directives

To keep code inline, set externalize_code: false in n8n/manifests/workflows.yaml before running n8n-gitops export.

See Export for more details.

4. Commit to Git​

git init
git add .
git commit -m "Initial workflow export"
git tag v1.0.0

5. Deploy workflows​

Deploy from working tree:

n8n-gitops deploy

Deploy from a specific Git tag:

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

Dry run to preview changes:

n8n-gitops deploy --dry-run

See Deployment for more details.

  1. Export existing workflows: n8n-gitops export
  2. Commit to Git: git add . && git commit -m "Initial export"
  3. Validate: n8n-gitops validate --strict
  4. Tag release: git tag v1.0.0
  5. Deploy: n8n-gitops deploy --git-ref v1.0.0

Next Steps​