Contributing to n8n Hosting

Commit Messages

This project uses Conventional Commits for automated versioning. Your commit messages must follow this format:

<type>(<scope>): <description>

[optional body]

Types:

• feat -- new feature (triggers minor version bump)
• fix -- bug fix (triggers patch version bump)
• docs -- documentation changes
• refactor -- code refactoring
• perf -- performance improvements
• chore(no-release) -- no version bump

Examples:

feat(chart): add webhook processor ingress support
fix(worker): add missing extraEnvFrom to worker deployment
docs: update README with OCI install instructions

Chart Development

Prerequisites

• Helm 3.12+
• chart-testing (ct) for linting
• helm-unittest 1.1+ for unit tests, which needs Helm 3.18+

Local Linting

helm lint charts/n8n
ct lint --charts charts/n8n --validate-maintainers=false

Unit Tests

The unit tests live in charts/n8n/tests/. Install the plugin once:

helm plugin install https://github.com/helm-unittest/helm-unittest.git --version v1.1.2

On Helm 4, add --verify=false to that command. Then run both passes:

helm unittest --strict charts/n8n
helm unittest --strict --skip-schema-validation -f 'tests/without-schema/*_test.yaml' charts/n8n

The second pass covers validation that values.schema.json also enforces, so it runs with schema validation off.

tests/default-render_test.yaml compares the default render with a stored snapshot. If your change alters that output on purpose, run helm unittest -u charts/n8n and commit the updated file in tests/__snapshot__/.

Template Validation

Render all templates to check for syntax errors and inspect the generated YAML:

# Render with minimal values
helm template test charts/n8n -f charts/n8n/examples/minimal.yaml

# Render with all features enabled
helm template test charts/n8n -f charts/n8n/examples/production-s3.yaml

# Save output for inspection
helm template test charts/n8n -f charts/n8n/examples/minimal.yaml > /tmp/rendered.yaml

Local Install Test

Prerequisites: A local Kubernetes environment with Docker support. Any of these work:

• OrbStack (recommended for macOS — lightweight, has built-in Kubernetes)
• Docker Desktop with Kubernetes enabled
• kind (Kubernetes-in-Docker — requires Docker)

If using kind, create a cluster first: kind create cluster --name n8n-test

Option A: Standalone mode (quickest — no external dependencies)

This deploys a single n8n pod with SQLite. No PostgreSQL or Redis needed.

# Create namespace and secrets
kubectl create namespace n8n-test
kubectl create secret generic n8n-secrets -n n8n-test \
  --from-literal=N8N_ENCRYPTION_KEY=$(openssl rand -hex 32) \
  --from-literal=N8N_HOST=localhost \
  --from-literal=N8N_PORT=5678 \
  --from-literal=N8N_PROTOCOL=http

# Install with standalone example
helm install n8n charts/n8n -n n8n-test \
  -f charts/n8n/examples/standalone.yaml

# Wait for the pod to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/component=main -n n8n-test --timeout=120s

# Access the UI (keep running, Ctrl+C to stop)
kubectl port-forward svc/n8n-main -n n8n-test 5678:5678

Open http://localhost:5678 in your browser.

Clean up:

helm uninstall n8n -n n8n-test
kubectl delete namespace n8n-test

Option B: Queue mode (full deployment with PostgreSQL + Redis)

This deploys the chart with external PostgreSQL and Redis, plus worker pods — closer to a production setup.

1. Deploy dependencies

# Create a test namespace
kubectl create namespace n8n-test

# Add the Bitnami Helm repo
helm repo add bitnami https://charts.bitnami.com/bitnami

# Deploy PostgreSQL and Redis
helm install postgres bitnami/postgresql -n n8n-test \
  --set auth.postgresPassword=postgres \
  --set auth.database=n8n
helm install redis bitnami/redis -n n8n-test \
  --set auth.password=redis \
  --set architecture=standalone

# Wait for databases to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=postgresql -n n8n-test --timeout=120s
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=redis -n n8n-test --timeout=120s

2. Create secrets and install the chart

# Create the required n8n secrets
kubectl create secret generic n8n-secrets -n n8n-test \
  --from-literal=N8N_ENCRYPTION_KEY=$(openssl rand -hex 32) \
  --from-literal=N8N_HOST=localhost \
  --from-literal=N8N_PORT=5678 \
  --from-literal=N8N_PROTOCOL=http

# Install the chart
helm install n8n charts/n8n -n n8n-test \
  --set database.host=postgres-postgresql \
  --set database.user=postgres \
  --set database.passwordSecret.name=postgres-postgresql \
  --set database.passwordSecret.key=postgres-password \
  --set redis.host=redis-master \
  --set redis.passwordSecret.name=redis \
  --set redis.passwordSecret.key=redis-password \
  --set secretRefs.existingSecret=n8n-secrets

# Watch pods come up (Ctrl+C when all show Running/Ready)
kubectl get pods -n n8n-test -w

3. Access the UI

The n8n service uses ClusterIP by default, so it's only reachable from inside the cluster. Use port-forwarding to access it from your browser:

kubectl port-forward svc/n8n-main -n n8n-test 5678:5678

Then open http://localhost:5678. Keep the port-forward running — it will stop when you Ctrl+C.

4. Clean up

helm uninstall n8n -n n8n-test
helm uninstall redis -n n8n-test
helm uninstall postgres -n n8n-test
kubectl delete namespace n8n-test

# If using kind:
kind delete cluster --name n8n-test

Maintainers can label PRs with test-install to run the tests with CI.

Version Bumps

Do not manually edit Chart.yaml version. Release Please bumps it automatically based on commit messages.

The n8n version is a separate thing to the chart version. It is pinned in multiple files across the various deployment artefacts.

The bump-n8n-version workflow runs this script every Wednesday to follow n8n's stable release cadence, once for each release branch. Each branch stays within the n8n major it is already on. If you do need to bump the versions by hand, you can do so by running:

scripts/bump-n8n-version.sh 2.38.6

Pull Requests

Open your PR against main, which is where chart 2.0 is being built. Chart 1.x is maintained on release/n8n-2.x, and maintainers bring fixes across to it with the backport release/n8n-2.x label. Open a PR against release/n8n-2.x directly only when the fix is for code that no longer exists on main, or when a backport conflicts and has to be written by hand.

• Add the test-install label to PRs that change chart templates to trigger a full install test on a kind cluster
• Add the test-install-v3-rc label to PRs against main to run the same install test on the newest n8n 3 release candidate
• Add the test-upgrade label to PRs against main that change chart templates or examples. It installs the last 1.x release on a kind cluster with each example that has a ci/install/ overlay on both branches, then upgrades it in place to the PR's chart and examples
• All PRs must pass lint and template validation checks

License

By contributing, you agree that your contributions will be licensed under the MIT License.