---
name: n8n_workflow_automation
description: Run n8n as agent infrastructure. Use when self-hosting n8n for production (Docker Compose, Postgres, queue mode), designing resilient workflows with retries and error workflows, or wiring credentials through external secrets vaults instead of hardcoding them.
---

# n8n Workflow Automation

## Purpose

n8n is a fair-code workflow automation platform (visual node graphs, 400+ integrations, self-host or managed). Agents use it as the execution layer for recurring jobs: webhooks in, sub-workflows out, alerts on failure. This skill covers the three things the official docs scatter across separate pages: a production self-hosted setup, error handling that survives unattended runs, and credentials that live in a real vault.

## Workflow

1. Decide Cloud vs self-hosted. Cloud is the managed option with no setup. Self-hosted Community Edition is free and carries almost the full feature set; SSO, environments, and projects need paid tiers. Registered (free) Community adds folders and debugging. If the agent needs full control of data or custom infra, go self-hosted.
2. For self-hosted production, deploy with Docker Compose plus Postgres (not SQLite). One Compose file holds the service, the database, the volume, and the env vars, so the whole setup is reviewable and repeatable. See `references/self-hosting.md` for a working template.
3. When a single instance stops keeping up, switch on queue mode: set `EXECUTIONS_MODE=queue` on main and workers, point at Redis, share one `N8N_ENCRYPTION_KEY` everywhere, and keep Postgres 13 or newer. Main takes triggers and webhooks; workers run the jobs. Without `EXECUTIONS_MODE=queue`, adding workers does nothing.
4. Build the error story before the workflow goes live: turn on Retry On Fail on every node that touches a network service (the engine caps Max Tries at 5 and Wait Between Tries at 5000ms), route real failures to a dedicated error workflow via Workflow Settings, and write that handler to start with the Error Trigger node. The handler reacts to the failure, logs, and alerts. It never re-runs the failed workflow and never re-enters itself.
5. Put secrets in the vault, not the workflow. Pick one store (1Password Connect, AWS Secrets Manager, Vault, Infisical, Azure Key Vault, or GCP Secrets Manager) and reference secrets at execution time. Never hardcode a token in a node parameter, never commit `.env`, and never fetch secrets with an HTTP Request node, because values pulled that way land in execution data by default.

## Output Contract

A production n8n handoff delivers:

- `compose.yaml` + `.env` for the self-hosted stack (Postgres, persistent volume, encryption key, webhook URLs), matching the template in `references/self-hosting.md`.
- Each workflow wired to a shared error workflow via its Error Workflow setting, with node-level retries on every network call.
- Credentials referenced from an external secrets store or env var, never inline. If the vault needs the n8n Enterprise external-secrets feature, say so plainly instead of improvising.
- An update plan: read the release notes, back up the database, `docker compose pull`, then restart.

## Operating Rules

1. Every factual claim about n8n (version behavior, node names, env vars, caps) must be verified against docs.n8n.io or the official n8n-io/skills repo. Unverifiable = cut it.
2. Retries absorb transient failures only (timeouts, 429s, brief 5xx). Never retry a 401 or malformed input; fix the cause.
3. A retried write must be idempotent. Retries that create duplicate records are a bug, so use idempotency keys or check-then-create on side-effect calls.
4. The error handler workflow has no error workflow of its own. One reason: a handler that fails must not re-trigger itself.
5. The same `N8N_ENCRYPTION_KEY` must be set on main and every worker and webhook processor. A mismatch means workers cannot decrypt credentials and executions fail.
6. Exported workflow JSON contains credential names and IDs. Sanitize before sharing.