| Name | n8n-workflow-builder JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A Python library for building, managing, and deploying n8n workflows with configuration-driven templates |
| upload_time | 2025-08-03 04:55:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
n8n
workflow
automation
template
deployment
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# n8n Workflow Builder
A Python library for building, managing, and deploying n8n workflows with a configuration-driven approach. This package provides the core tooling while allowing you to maintain your own private repository of workflows and templates.
## Features
- **Config-driven workflow management** using YAML configuration files
- **Template system** for parameterized workflows using Jinja2
- **Secure secrets management** with .env file integration
- **CLI interface** with build, pull, push, and compare commands
- **Workflow comparison** to track differences between local and remote workflows
- **n8n API integration** for seamless workflow deployment
## Installation
### Install from PyPI (Recommended)
```bash
# Install the latest stable version
pip install n8n-workflow-builder
# Install with development dependencies (for contributing)
pip install n8n-workflow-builder[dev]
```
### Install from Source
```bash
# Clone and install in development mode
git clone https://github.com/ferrants/n8n-workflow-builder.git
cd n8n-workflow-builder
pip install -e .
```
## Setting Up Your Workflow Repository
After installing the library, you'll need to create your own repository to store workflows, templates, and configuration. This repository should be private to your organization.
### 1. Create Your Workflow Repository
```bash
# Create a new repository for your workflows
mkdir my-n8n-workflows
cd my-n8n-workflows
git init
# Create the recommended directory structure
mkdir -p templates workflows built_workflows pulled_workflows
```
### 2. Set Up Configuration Files
Create your environment file:
```
# Create .env file with your n8n credentials
N8N_API_KEY=your_n8n_api_key_here
```
Create your configuration file:
```
n8n_instance:
name: "Production n8n"
url: "https://your-n8n-instance.com"
api_key_env: "N8N_API_KEY"
output_dir: "built_workflows"
pulled_dir: "pulled_workflows"
workflows:
# Add your workflow definitions here
# See examples below
```
### 3. Set Up Git Ignore
```
# Environment files
.env
.env.local
# Generated workflows
built_workflows/
pulled_workflows/
# Python
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
*.so
.coverage
.pytest_cache/
# IDE
.vscode/
.idea/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
```
### 4. Quick Start
1. **Build workflows**:
```bash
n8n-workflow-builder build config.yaml
```
2. **Push to n8n**:
```bash
n8n-workflow-builder push config.yaml
```
### 5. Recommended Repository Structure
```
my-n8n-workflows/
├── templates/ # Jinja2 workflow templates
│ ├── data-sync.yaml # Reusable templates
│ └── email-scraper.yaml # Parameterized workflows
├── workflows/ # Static workflow files
│ └── legacy-workflow.json # Direct workflow files
├── built_workflows/ # Generated workflows (gitignored)
├── pulled_workflows/ # Downloaded workflows (gitignored)
├── config.yaml # Workflow definitions
├── .env # Environment variables (gitignored)
├── .gitignore # Git ignore rules
└── README.md # Your workflow documentation
```
## Configuration
### Environment Variables (.env)
```env
N8N_API_KEY=your_n8n_api_key_here
```
### Configuration File (config.yaml)
```yaml
n8n_instance:
name: "Production n8n"
url: "https://your-n8n-instance.com"
api_key_env: "N8N_API_KEY"
output_dir: "built_workflows"
pulled_dir: "pulled_workflows"
workflows:
# Direct workflow file reference
- name: "user-onboarding"
file: "workflows/user-onboarding.json"
description: "Handles new user onboarding process"
# Template-based workflow
- name: "data-sync-customers"
template: "templates/data-sync.yaml"
description: "Syncs customer data between systems"
parameters:
source_system: "salesforce"
target_system: "hubspot"
sync_interval: "hourly"
fields: ["name", "email", "company"]
```
## CLI Commands
### Build Workflows
Build all workflows defined in the configuration:
```bash
# Build all workflows
n8n-workflow-builder build config.yaml
# Build a specific workflow by name
n8n-workflow-builder build config.yaml --workflow user-onboarding
n8n-workflow-builder build config.yaml -w user-onboarding
```
### Pull Workflows
Download workflows from your n8n instance:
```bash
# Pull all workflows
n8n-workflow-builder pull config.yaml
# Pull a specific workflow by name
n8n-workflow-builder pull config.yaml --workflow user-onboarding
n8n-workflow-builder pull config.yaml -w user-onboarding
```
### Push Workflows
Upload built workflows to your n8n instance:
```bash
# Push all workflows
n8n-workflow-builder push config.yaml
# Push a specific workflow by name
n8n-workflow-builder push config.yaml --workflow user-onboarding
n8n-workflow-builder push config.yaml -w user-onboarding
# Dry run to see what would be uploaded
n8n-workflow-builder push config.yaml --dry-run
# Dry run for a specific workflow
n8n-workflow-builder push config.yaml --workflow my-workflow --dry-run
```
### Compare Workflows
Compare built workflows with pulled workflows:
```bash
# Compare all workflows
n8n-workflow-builder compare config.yaml
# Compare a specific workflow by name
n8n-workflow-builder compare config.yaml --workflow user-onboarding
n8n-workflow-builder compare config.yaml -w user-onboarding
# Output as JSON
n8n-workflow-builder compare config.yaml --format json
# Compare single workflow with JSON output
n8n-workflow-builder compare config.yaml --workflow my-workflow --format json
```
## Library Architecture
The n8n-workflow-builder library is structured as follows:
```
n8n_workflow_builder/ # Core library package
├── models/ # Data models
│ └── config.py # Configuration models
├── services/ # Business logic
│ ├── secrets.py # Secrets management
│ ├── builder.py # Workflow builder
│ ├── n8n_client.py # n8n API client
│ └── comparator.py # Workflow comparison
├── utils/ # Utilities
│ └── validation.py # Validation helpers
└── cli.py # Command line interface
```
## Publishing the Library
### For Library Maintainers
To publish this library to PyPI:
1. **Update version in pyproject.toml**
2. **Build the package**:
```bash
python -m build
```
3. **Upload to PyPI**:
```bash
python -m twine upload dist/*
```
### Package Configuration
The library should be configured in `pyproject.toml` with:
```toml
[project]
name = "n8n-workflow-builder"
version = "1.0.0"
description = "A Python library for building, managing, and deploying n8n workflows"
authors = [{name = "Your Name", email = "your.email@example.com"}]
license = {text = "MIT"}
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
"click>=8.0.0",
"pyyaml>=6.0",
"python-dotenv>=0.19.0",
"requests>=2.25.0",
"jinja2>=3.0.0",
"jsonschema>=4.0.0"
]
[project.optional-dependencies]
dev = [
"pytest>=7.0.0",
"pytest-cov>=4.0.0",
"black>=22.0.0",
"flake8>=5.0.0",
"mypy>=1.0.0"
]
[project.scripts]
n8n-workflow-builder = "n8n_workflow_builder.cli:main"
[project.urls]
Homepage = "https://github.com/ferrants/n8n-workflow-builder"
Repository = "https://github.com/ferrants/n8n-workflow-builder"
Issues = "https://github.com/ferrants/n8n-workflow-builder/issues"
```
n8n_workflows/
├── src/n8n_workflow_builder/ # Main package
│ ├── models/ # Data models
│ │ └── config.py # Configuration models
│ ├── services/ # Business logic
│ │ ├── secrets.py # Secrets management
│ │ ├── builder.py # Workflow builder
│ │ ├── n8n_client.py # n8n API client
│ │ └── comparator.py # Workflow comparison
│ ├── utils/ # Utilities
│ │ └── validation.py # Validation helpers
│ └── cli.py # Command line interface
├── templates/ # Workflow templates
├── workflows/ # Static workflow files
├── built_workflows/ # Generated workflows (output)
├── pulled_workflows/ # Downloaded workflows
├── tests/ # Test files
├── config.example.yaml # Example configuration
├── .env.example # Example environment file
└── pyproject.toml # Package configuration
```
## Creating Templates
### Template System Overview
Templates use Jinja2 syntax and have access to:
- `workflow_name`: The name of the workflow being built
- `parameters`: Parameters defined in the configuration
- `secrets`: Non-sensitive configuration values
### Template Format Requirements
- **Templates must be JSON format** (despite `.yaml` extension)
- Templates are processed by Jinja2 before being parsed as JSON
- **Critical**: n8n expressions like `{{ $json.field }}` must be escaped
### Creating Templates from Existing Workflows
1. **Pull an existing workflow**:
```bash
n8n-workflow-builder pull config.yaml --workflow my-workflow
```
2. **Copy and parameterize**:
```bash
cp pulled_workflows/my-workflow.json templates/my-template.yaml
```
3. **Remove volatile fields** (id, createdAt, updatedAt, versionId, shared, etc.)
4. **Parameterize values**:
```json
{
"name": "{{ workflow_name }}",
"nodes": [
{
"parameters": {
"url": "https://api.example.com/{{ parameters.endpoint }}",
"limit": {{ parameters.limit | default(10) }}
}
}
]
}
```
5. **Escape n8n expressions**:
```json
{
"parameters": {
"leftValue": "={{ '{{' }} {{ '$' }}json.website {{ '}}' }}",
"jsCode": "const input = {{ '$' }}input.first().json.data"
}
}
```
6. **Add credential references**:
```json
{
"credentials": {
"googleSheetsOAuth2Api": {
"id": "{{ parameters.google_sheets_credential_id }}",
"name": "Google Sheets account"
}
}
}
```
### Template Testing Workflow
1. **Build and compare**:
```bash
n8n-workflow-builder build config.yaml --workflow my-workflow
n8n-workflow-builder compare config.yaml --workflow my-workflow
```
2. **Test deployment**:
```bash
n8n-workflow-builder push config.yaml --workflow my-workflow --dry-run
```
### Example Template
Example template (`templates/data-sync.yaml`):
```json
{
"name": "{{ workflow_name }}",
"nodes": [
{
"name": "Get {{ parameters.source_system | title }} Data",
"type": "n8n-nodes-base.{{ parameters.source_system }}",
"parameters": {
"fields": {{ parameters.fields | tojson }},
"url": "{{ parameters.api_url | urlencode }}"
},
"credentials": {
"{{ parameters.credential_type }}": {
"id": "{{ parameters.credential_id }}",
"name": "{{ parameters.credential_name }}"
}
}
}
]
}
```
## Best Practices for Your Workflow Repository
### Version Control
- **Keep templates and config in git**: Track your workflow definitions and templates
- **Exclude sensitive data**: Never commit `.env` files or API keys
- **Exclude generated files**: Don't commit `built_workflows/` or `pulled_workflows/`
### Organization
- **Use descriptive names**: Name workflows and templates clearly
- **Group related workflows**: Use prefixes or directories for organization
- **Document parameters**: Add comments in config.yaml explaining parameters
### Security
- **Use environment variables**: Store API keys and secrets in `.env`
- **Separate environments**: Use different config files for dev/staging/prod
- **Credential management**: Reference credential IDs as parameters, not hardcoded
### Testing
- **Compare before deploying**: Always run compare to check differences
- **Use dry-run**: Test deployments with `--dry-run` flag
- **Single workflow testing**: Use `--workflow` flag during development
### Example Workflow Repository
See our [example workflow repository](https://github.com/ferrants/n8n-workflows-example) for a complete setup with:
- Multiple environment configurations
- Reusable templates
- CI/CD pipeline examples
- Documentation templates
## Contributing to the Library
### Development Setup
```bash
git clone https://github.com/ferrants/n8n-workflow-builder.git
cd n8n-workflow-builder
pip install -e ".[dev]"
```
### Running Tests
```bash
make test
```
### Code Formatting
```bash
make format
```
### Linting
```bash
make lint
```
## Main Components
- **Workflows**: Static JSON files or template-generated workflows
- **Templates**: Jinja2 templates for parameterized workflows
- **Builder**: Processes configuration and builds concrete n8n workflows
- **n8n Client**: Handles API communication with n8n instances
- **Comparator**: Compares built workflows with deployed workflows
- **Secrets Service**: Secure management of API keys and sensitive data
## API Reference
The package provides several key services:
- `SecretsService`: Manages environment variables and API keys
- `WorkflowBuilder`: Builds workflows from configuration
- `N8nClient`: Communicates with n8n REST API
- `WorkflowComparator`: Compares workflow versions
Raw data
{
"_id": null,
"home_page": null,
"name": "n8n-workflow-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "n8n, workflow, automation, template, deployment",
"author": null,
"author_email": "Matt Ferrante <matt@heyferrante.com>",
"download_url": "https://files.pythonhosted.org/packages/e3/f0/0ff744435126e08e11ded284f73e368594fa026f89947ca3e88e449c4ede/n8n_workflow_builder-0.2.0.tar.gz",
"platform": null,
"description": "# n8n Workflow Builder\n\nA Python library for building, managing, and deploying n8n workflows with a configuration-driven approach. This package provides the core tooling while allowing you to maintain your own private repository of workflows and templates.\n\n## Features\n\n- **Config-driven workflow management** using YAML configuration files\n- **Template system** for parameterized workflows using Jinja2\n- **Secure secrets management** with .env file integration\n- **CLI interface** with build, pull, push, and compare commands\n- **Workflow comparison** to track differences between local and remote workflows\n- **n8n API integration** for seamless workflow deployment\n\n## Installation\n\n### Install from PyPI (Recommended)\n```bash\n# Install the latest stable version\npip install n8n-workflow-builder\n\n# Install with development dependencies (for contributing)\npip install n8n-workflow-builder[dev]\n```\n\n### Install from Source\n```bash\n# Clone and install in development mode\ngit clone https://github.com/ferrants/n8n-workflow-builder.git\ncd n8n-workflow-builder\npip install -e .\n```\n\n## Setting Up Your Workflow Repository\n\nAfter installing the library, you'll need to create your own repository to store workflows, templates, and configuration. This repository should be private to your organization.\n\n### 1. Create Your Workflow Repository\n\n```bash\n# Create a new repository for your workflows\nmkdir my-n8n-workflows\ncd my-n8n-workflows\ngit init\n\n# Create the recommended directory structure\nmkdir -p templates workflows built_workflows pulled_workflows\n```\n\n### 2. Set Up Configuration Files\n\nCreate your environment file:\n```\n# Create .env file with your n8n credentials\nN8N_API_KEY=your_n8n_api_key_here\n```\n\nCreate your configuration file:\n```\nn8n_instance:\n name: \"Production n8n\"\n url: \"https://your-n8n-instance.com\"\n api_key_env: \"N8N_API_KEY\"\n\noutput_dir: \"built_workflows\"\npulled_dir: \"pulled_workflows\"\n\nworkflows:\n # Add your workflow definitions here\n # See examples below\n```\n\n### 3. Set Up Git Ignore\n\n```\n# Environment files\n.env\n.env.local\n\n# Generated workflows\nbuilt_workflows/\npulled_workflows/\n\n# Python\n__pycache__/\n*.pyc\n*.pyo\n*.pyd\n.Python\n*.so\n.coverage\n.pytest_cache/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n\n# OS\n.DS_Store\nThumbs.db\n```\n\n### 4. Quick Start\n\n1. **Build workflows**:\n ```bash\n n8n-workflow-builder build config.yaml\n ```\n\n2. **Push to n8n**:\n ```bash\n n8n-workflow-builder push config.yaml\n ```\n\n### 5. Recommended Repository Structure\n\n```\nmy-n8n-workflows/\n\u251c\u2500\u2500 templates/ # Jinja2 workflow templates\n\u2502 \u251c\u2500\u2500 data-sync.yaml # Reusable templates\n\u2502 \u2514\u2500\u2500 email-scraper.yaml # Parameterized workflows\n\u251c\u2500\u2500 workflows/ # Static workflow files\n\u2502 \u2514\u2500\u2500 legacy-workflow.json # Direct workflow files\n\u251c\u2500\u2500 built_workflows/ # Generated workflows (gitignored)\n\u251c\u2500\u2500 pulled_workflows/ # Downloaded workflows (gitignored)\n\u251c\u2500\u2500 config.yaml # Workflow definitions\n\u251c\u2500\u2500 .env # Environment variables (gitignored)\n\u251c\u2500\u2500 .gitignore # Git ignore rules\n\u2514\u2500\u2500 README.md # Your workflow documentation\n```\n\n## Configuration\n\n### Environment Variables (.env)\n\n```env\nN8N_API_KEY=your_n8n_api_key_here\n```\n\n### Configuration File (config.yaml)\n\n```yaml\nn8n_instance:\n name: \"Production n8n\"\n url: \"https://your-n8n-instance.com\"\n api_key_env: \"N8N_API_KEY\"\n\noutput_dir: \"built_workflows\"\npulled_dir: \"pulled_workflows\"\n\nworkflows:\n # Direct workflow file reference\n - name: \"user-onboarding\"\n file: \"workflows/user-onboarding.json\"\n description: \"Handles new user onboarding process\"\n \n # Template-based workflow\n - name: \"data-sync-customers\"\n template: \"templates/data-sync.yaml\"\n description: \"Syncs customer data between systems\"\n parameters:\n source_system: \"salesforce\"\n target_system: \"hubspot\"\n sync_interval: \"hourly\"\n fields: [\"name\", \"email\", \"company\"]\n```\n\n## CLI Commands\n\n### Build Workflows\nBuild all workflows defined in the configuration:\n```bash\n# Build all workflows\nn8n-workflow-builder build config.yaml\n\n# Build a specific workflow by name\nn8n-workflow-builder build config.yaml --workflow user-onboarding\nn8n-workflow-builder build config.yaml -w user-onboarding\n```\n\n### Pull Workflows\nDownload workflows from your n8n instance:\n```bash\n# Pull all workflows\nn8n-workflow-builder pull config.yaml\n\n# Pull a specific workflow by name\nn8n-workflow-builder pull config.yaml --workflow user-onboarding\nn8n-workflow-builder pull config.yaml -w user-onboarding\n```\n\n### Push Workflows\nUpload built workflows to your n8n instance:\n```bash\n# Push all workflows\nn8n-workflow-builder push config.yaml\n\n# Push a specific workflow by name\nn8n-workflow-builder push config.yaml --workflow user-onboarding\nn8n-workflow-builder push config.yaml -w user-onboarding\n\n# Dry run to see what would be uploaded\nn8n-workflow-builder push config.yaml --dry-run\n\n# Dry run for a specific workflow\nn8n-workflow-builder push config.yaml --workflow my-workflow --dry-run\n```\n\n### Compare Workflows\nCompare built workflows with pulled workflows:\n```bash\n# Compare all workflows\nn8n-workflow-builder compare config.yaml\n\n# Compare a specific workflow by name\nn8n-workflow-builder compare config.yaml --workflow user-onboarding\nn8n-workflow-builder compare config.yaml -w user-onboarding\n\n# Output as JSON\nn8n-workflow-builder compare config.yaml --format json\n\n# Compare single workflow with JSON output\nn8n-workflow-builder compare config.yaml --workflow my-workflow --format json\n```\n\n## Library Architecture\n\nThe n8n-workflow-builder library is structured as follows:\n\n```\nn8n_workflow_builder/ # Core library package\n\u251c\u2500\u2500 models/ # Data models\n\u2502 \u2514\u2500\u2500 config.py # Configuration models\n\u251c\u2500\u2500 services/ # Business logic\n\u2502 \u251c\u2500\u2500 secrets.py # Secrets management\n\u2502 \u251c\u2500\u2500 builder.py # Workflow builder\n\u2502 \u251c\u2500\u2500 n8n_client.py # n8n API client\n\u2502 \u2514\u2500\u2500 comparator.py # Workflow comparison\n\u251c\u2500\u2500 utils/ # Utilities\n\u2502 \u2514\u2500\u2500 validation.py # Validation helpers\n\u2514\u2500\u2500 cli.py # Command line interface\n```\n\n## Publishing the Library\n\n### For Library Maintainers\n\nTo publish this library to PyPI:\n\n1. **Update version in pyproject.toml**\n2. **Build the package**:\n ```bash\n python -m build\n ```\n3. **Upload to PyPI**:\n ```bash\n python -m twine upload dist/*\n ```\n\n### Package Configuration\n\nThe library should be configured in `pyproject.toml` with:\n\n```toml\n[project]\nname = \"n8n-workflow-builder\"\nversion = \"1.0.0\"\ndescription = \"A Python library for building, managing, and deploying n8n workflows\"\nauthors = [{name = \"Your Name\", email = \"your.email@example.com\"}]\nlicense = {text = \"MIT\"}\nreadme = \"README.md\"\nrequires-python = \">=3.8\"\ndependencies = [\n \"click>=8.0.0\",\n \"pyyaml>=6.0\",\n \"python-dotenv>=0.19.0\",\n \"requests>=2.25.0\",\n \"jinja2>=3.0.0\",\n \"jsonschema>=4.0.0\"\n]\n\n[project.optional-dependencies]\ndev = [\n \"pytest>=7.0.0\",\n \"pytest-cov>=4.0.0\",\n \"black>=22.0.0\",\n \"flake8>=5.0.0\",\n \"mypy>=1.0.0\"\n]\n\n[project.scripts]\nn8n-workflow-builder = \"n8n_workflow_builder.cli:main\"\n\n[project.urls]\nHomepage = \"https://github.com/ferrants/n8n-workflow-builder\"\nRepository = \"https://github.com/ferrants/n8n-workflow-builder\"\nIssues = \"https://github.com/ferrants/n8n-workflow-builder/issues\"\n```\nn8n_workflows/\n\u251c\u2500\u2500 src/n8n_workflow_builder/ # Main package\n\u2502 \u251c\u2500\u2500 models/ # Data models\n\u2502 \u2502 \u2514\u2500\u2500 config.py # Configuration models\n\u2502 \u251c\u2500\u2500 services/ # Business logic\n\u2502 \u2502 \u251c\u2500\u2500 secrets.py # Secrets management\n\u2502 \u2502 \u251c\u2500\u2500 builder.py # Workflow builder\n\u2502 \u2502 \u251c\u2500\u2500 n8n_client.py # n8n API client\n\u2502 \u2502 \u2514\u2500\u2500 comparator.py # Workflow comparison\n\u2502 \u251c\u2500\u2500 utils/ # Utilities\n\u2502 \u2502 \u2514\u2500\u2500 validation.py # Validation helpers\n\u2502 \u2514\u2500\u2500 cli.py # Command line interface\n\u251c\u2500\u2500 templates/ # Workflow templates\n\u251c\u2500\u2500 workflows/ # Static workflow files\n\u251c\u2500\u2500 built_workflows/ # Generated workflows (output)\n\u251c\u2500\u2500 pulled_workflows/ # Downloaded workflows\n\u251c\u2500\u2500 tests/ # Test files\n\u251c\u2500\u2500 config.example.yaml # Example configuration\n\u251c\u2500\u2500 .env.example # Example environment file\n\u2514\u2500\u2500 pyproject.toml # Package configuration\n```\n\n## Creating Templates\n\n### Template System Overview\n\nTemplates use Jinja2 syntax and have access to:\n\n- `workflow_name`: The name of the workflow being built\n- `parameters`: Parameters defined in the configuration\n- `secrets`: Non-sensitive configuration values\n\n### Template Format Requirements\n\n- **Templates must be JSON format** (despite `.yaml` extension)\n- Templates are processed by Jinja2 before being parsed as JSON\n- **Critical**: n8n expressions like `{{ $json.field }}` must be escaped\n\n### Creating Templates from Existing Workflows\n\n1. **Pull an existing workflow**:\n ```bash\n n8n-workflow-builder pull config.yaml --workflow my-workflow\n ```\n\n2. **Copy and parameterize**:\n ```bash\n cp pulled_workflows/my-workflow.json templates/my-template.yaml\n ```\n\n3. **Remove volatile fields** (id, createdAt, updatedAt, versionId, shared, etc.)\n\n4. **Parameterize values**:\n ```json\n {\n \"name\": \"{{ workflow_name }}\",\n \"nodes\": [\n {\n \"parameters\": {\n \"url\": \"https://api.example.com/{{ parameters.endpoint }}\",\n \"limit\": {{ parameters.limit | default(10) }}\n }\n }\n ]\n }\n ```\n\n5. **Escape n8n expressions**:\n ```json\n {\n \"parameters\": {\n \"leftValue\": \"={{ '{{' }} {{ '$' }}json.website {{ '}}' }}\",\n \"jsCode\": \"const input = {{ '$' }}input.first().json.data\"\n }\n }\n ```\n\n6. **Add credential references**:\n ```json\n {\n \"credentials\": {\n \"googleSheetsOAuth2Api\": {\n \"id\": \"{{ parameters.google_sheets_credential_id }}\",\n \"name\": \"Google Sheets account\"\n }\n }\n }\n ```\n\n### Template Testing Workflow\n\n1. **Build and compare**:\n ```bash\n n8n-workflow-builder build config.yaml --workflow my-workflow\n n8n-workflow-builder compare config.yaml --workflow my-workflow\n ```\n\n2. **Test deployment**:\n ```bash\n n8n-workflow-builder push config.yaml --workflow my-workflow --dry-run\n ```\n\n### Example Template\n\nExample template (`templates/data-sync.yaml`):\n```json\n{\n \"name\": \"{{ workflow_name }}\",\n \"nodes\": [\n {\n \"name\": \"Get {{ parameters.source_system | title }} Data\",\n \"type\": \"n8n-nodes-base.{{ parameters.source_system }}\",\n \"parameters\": {\n \"fields\": {{ parameters.fields | tojson }},\n \"url\": \"{{ parameters.api_url | urlencode }}\"\n },\n \"credentials\": {\n \"{{ parameters.credential_type }}\": {\n \"id\": \"{{ parameters.credential_id }}\",\n \"name\": \"{{ parameters.credential_name }}\"\n }\n }\n }\n ]\n}\n```\n\n## Best Practices for Your Workflow Repository\n\n### Version Control\n- **Keep templates and config in git**: Track your workflow definitions and templates\n- **Exclude sensitive data**: Never commit `.env` files or API keys\n- **Exclude generated files**: Don't commit `built_workflows/` or `pulled_workflows/`\n\n### Organization\n- **Use descriptive names**: Name workflows and templates clearly\n- **Group related workflows**: Use prefixes or directories for organization\n- **Document parameters**: Add comments in config.yaml explaining parameters\n\n### Security\n- **Use environment variables**: Store API keys and secrets in `.env`\n- **Separate environments**: Use different config files for dev/staging/prod\n- **Credential management**: Reference credential IDs as parameters, not hardcoded\n\n### Testing\n- **Compare before deploying**: Always run compare to check differences\n- **Use dry-run**: Test deployments with `--dry-run` flag\n- **Single workflow testing**: Use `--workflow` flag during development\n\n### Example Workflow Repository\n\nSee our [example workflow repository](https://github.com/ferrants/n8n-workflows-example) for a complete setup with:\n- Multiple environment configurations\n- Reusable templates\n- CI/CD pipeline examples\n- Documentation templates\n\n## Contributing to the Library\n\n### Development Setup\n```bash\ngit clone https://github.com/ferrants/n8n-workflow-builder.git\ncd n8n-workflow-builder\npip install -e \".[dev]\"\n```\n\n### Running Tests\n```bash\nmake test\n```\n\n### Code Formatting\n```bash\nmake format\n```\n\n### Linting\n```bash\nmake lint\n```\n\n## Main Components\n\n- **Workflows**: Static JSON files or template-generated workflows\n- **Templates**: Jinja2 templates for parameterized workflows \n- **Builder**: Processes configuration and builds concrete n8n workflows\n- **n8n Client**: Handles API communication with n8n instances\n- **Comparator**: Compares built workflows with deployed workflows\n- **Secrets Service**: Secure management of API keys and sensitive data\n\n## API Reference\n\nThe package provides several key services:\n\n- `SecretsService`: Manages environment variables and API keys\n- `WorkflowBuilder`: Builds workflows from configuration\n- `N8nClient`: Communicates with n8n REST API\n- `WorkflowComparator`: Compares workflow versions\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python library for building, managing, and deploying n8n workflows with configuration-driven templates",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/ferrants/n8n-workflow-builder#readme",
"Homepage": "https://github.com/ferrants/n8n-workflow-builder",
"Issues": "https://github.com/ferrants/n8n-workflow-builder/issues",
"Repository": "https://github.com/ferrants/n8n-workflow-builder"
},
"split_keywords": [
"n8n",
" workflow",
" automation",
" template",
" deployment"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4fd0c58cc8c68a593eaeaf3413f8d3da64cc44965bc315ccadb06a528759fcb7",
"md5": "e9afe7b502060c639b92d3a75120b7ca",
"sha256": "b43b10d6d1bd5ee151d729d66687ce86703612225790bf25c034e4d0887b4cb0"
},
"downloads": -1,
"filename": "n8n_workflow_builder-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9afe7b502060c639b92d3a75120b7ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18675,
"upload_time": "2025-08-03T04:55:05",
"upload_time_iso_8601": "2025-08-03T04:55:05.605688Z",
"url": "https://files.pythonhosted.org/packages/4f/d0/c58cc8c68a593eaeaf3413f8d3da64cc44965bc315ccadb06a528759fcb7/n8n_workflow_builder-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e3f00ff744435126e08e11ded284f73e368594fa026f89947ca3e88e449c4ede",
"md5": "42aa2e82c1c61ed125f5218aa7a7ae47",
"sha256": "f20483d6cbb32d6bcc9a9870d0baf87dd6cbe5499946599e33c2a51e8204f206"
},
"downloads": -1,
"filename": "n8n_workflow_builder-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "42aa2e82c1c61ed125f5218aa7a7ae47",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20125,
"upload_time": "2025-08-03T04:55:06",
"upload_time_iso_8601": "2025-08-03T04:55:06.787020Z",
"url": "https://files.pythonhosted.org/packages/e3/f0/0ff744435126e08e11ded284f73e368594fa026f89947ca3e88e449c4ede/n8n_workflow_builder-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-03 04:55:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ferrants",
"github_project": "n8n-workflow-builder#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "n8n-workflow-builder"
}
