Onboarding: n8n-io/n8n

Generated by RepoPilot · 2026-05-04 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit today
• 5 active contributors
• Distributed ownership (top contributor 27%)
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

n8n is a self-hostable, fair-code workflow automation platform built primarily in TypeScript and Vue 3, enabling technical teams to visually wire together 400+ service integrations and custom JavaScript/Python code blocks into automated pipelines. It includes a native LangChain-based AI agent runtime for building LLM-powered workflows, and ships both a node-based visual editor and a full REST API backend. It solves the problem of needing full data control and code flexibility without sacrificing the speed of no-code tooling. Monorepo: the core runtime, CLI, editor UI, and 400+ integration nodes are split into separate packages (TypeScript for backend/nodes, Vue 3 for the frontend editor). The .claude/plugins/n8n/ directory contains repo-specific AI agent skills, commands, and scripts for developer workflow automation. Workflow scripts and quality checks live under a workflow-scripts package using Node.js native test runner.

Who it's for

DevOps engineers, backend developers, and technical operations teams who need to automate cross-service workflows (Slack + Postgres + HTTP APIs, etc.) with the ability to drop into real code, self-host behind a firewall, and avoid vendor lock-in from tools like Zapier or Make (Integromat).

Maturity & risk

n8n is production-ready and actively developed — it has 400+ integrations, a cloud offering, enterprise licensing, and a large community forum. The repo contains a .devcontainer setup, CI via .actrc, and a substantial TypeScript test suite. Commit activity and the presence of .claude/ AI-assisted development tooling suggest very active, ongoing development with a professional engineering team.

The fair-code Sustainable Use License (not OSI-approved open source) is a meaningful risk for commercial self-hosters — enterprise features require a paid license. The monorepo is very large (67MB+ of TypeScript alone) with complex interdependencies across packages, making upgrades and contributions non-trivial. The .claude/plugins/n8n/skills/ tooling and custom lint rules indicate significant internal toolchain investment that may not be documented for external contributors.

Active areas of work

The .claude/ directory with plugins, skills, and agents (including linear-issue-triager.md, spec-driven-development/SKILL.md, and create-community-node-lint-rule/SKILL.md) indicates active investment in AI-assisted engineering workflows. The protect-endpoints and node-add-oauth skills suggest active work on security hardening and OAuth node authoring. The workflow-scripts package with conventional-changelog and semver dependencies signals active release automation work.

Get running

git clone https://github.com/n8n-io/n8n.git && cd n8n && corepack enable && pnpm install && pnpm build && pnpm start

Or for instant local run without cloning:

npx n8n

Or via Docker:

docker volume create n8n_data && docker run -it --rm --name n8n -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

Daily commands: pnpm start # starts the full n8n server pnpm dev # starts in development/watch mode pnpm test # runs the test suite node --test --experimental-test-module-mocks ./.test.mjs ./quality/.test.mjs # runs workflow-scripts tests specifically

Map of the codebase

• .github/CLAUDE.md — Primary contributor guide for AI-assisted development, defining conventions, workflows, and how the Claude plugin system integrates with the n8n codebase.
• .claude/plugins/n8n/agents/developer.md — Core developer agent definition that governs how Claude assists with n8n development tasks, encoding architectural patterns and contribution conventions.
• .claude/plugins/n8n/skills/conventions/SKILL.md — Canonical coding conventions for the n8n repo — must be read before writing any code to understand naming, structure, and style expectations.
• .github/scripts/determine-version-info.mjs — Central versioning logic that drives releases; every release pipeline depends on this script to compute version bumps and validate semver.
• .github/scripts/bump-versions.mjs — Automates package version bumping across the monorepo, making it critical for understanding the release and publish workflow.
• .github/actions/ci-filter/ci-filter.mjs — Determines which CI jobs run for a given PR by analyzing changed file paths — directly controls CI cost and correctness.
• .github/scripts/docker/docker-tags.mjs — Defines the Docker image tagging strategy for all published n8n images, essential for understanding deployment artifact naming.

How to make changes

Add a new CI filter rule (include new package/path in CI)

1. Edit the path-matching logic to include the new package directory or file glob pattern so CI correctly activates for changes to it. (.github/actions/ci-filter/ci-filter.mjs)
2. Update the action definition if a new output variable or input parameter is needed for the new filter. (.github/actions/ci-filter/action.yml)
3. Add unit tests for the new path pattern to verify correct filtering behavior. (.github/actions/ci-filter/__tests__/ci-filter.test.ts)

Add a new Docker image tag variant for a release channel

1. Add the new tag pattern/logic (e.g. a new release channel like 'nightly') to the tag generation function. (.github/scripts/docker/docker-tags.mjs)
2. Update Docker config helpers if the new channel requires different build arguments or base images. (.github/scripts/docker/docker-config.mjs)
3. Reference the new tag variant in the Docker build action if it needs to be built and pushed separately. (.github/actions/build-n8n-docker/action.yml)

Add a new Claude developer skill (e.g. 'add-new-integration')

1. Create a new skill directory and SKILL.md file following the existing skill structure, defining the skill's purpose, steps, and examples. (.claude/plugins/n8n/skills/node-add-oauth/SKILL.md)
2. Register the new skill in the plugin manifest so it is discoverable by the Claude plugin system. (.claude/plugins/n8n/.claude-plugin/plugin.json)
3. Update the developer agent to reference the new skill when it is relevant to a developer request. (.claude/plugins/n8n/agents/developer.md)

Add a new release script (e.g. new validation step before publishing)

1. Create a new .mjs script in the scripts directory following the existing ESM module pattern, using @actions/github and @octokit/core for GitHub API calls. (.github/scripts/ensure-provenance-fields.mjs)
2. Write corresponding test file using Node.js built-in test runner with experimental module mocks. (.github/scripts/determine-version-info.test.mjs)
3. Wire the new script into the appropriate GitHub Actions workflow step, referencing it with 'node .github/scripts/your-script.mjs'. (.github/actions/setup-nodejs/action.yml)

Why these technologies

• Node.js ESM scripts (.mjs) — Allows release and CI scripts to run with zero build step using native Node.js, keeping the toolchain simple and the scripts auditable as plain JavaScript.
• @actions/github + @octokit/core — Official GitHub SDK for Actions provides typed access to GitHub APIs with automatic authentication, reducing boilerplate in release scripts.
• conventional-changelog — Automates changelog generation from commit messages following Angular commit convention, enabling reliable semver bumps without manual changelog curation.
• Docker multi-stage builds — Produces minimal production images while keeping build dependencies out of the runtime layer, critical for a self-hosted product where image size matters.
• Claude AI plugin system (.claude/) — Encodes institutional knowledge as machine-readable skills and agent definitions, enabling AI-assisted development that respects codebase conventions.

Trade-offs already made

• CI job filtering via path matching (ci-filter)

  • Why: Large monorepo with many packages means running all jobs on every commit is prohibitively expensive.
  • Consequence: Risk of false negatives if path patterns are not kept up to date with new package locations.

• Fair-code license (not fully open source)

  • Why: Enables sustainable commercial development while keeping source visible and self-hostable.
  • Consequence: Some contributors/companies may be unable to use n8n in certain commercial contexts, limiting ecosystem adoption vs. MIT-licensed alternatives.

• Monorepo with per-package versioning

  • Why: Allows independent release cadence for core, nodes, and editor packages while sharing tooling.
  • Consequence: Complex version bump scripts required; cross-package dependency updates must be coordinated carefully.

• AI-assisted development via Claude plugin

  • Why: Reduces onboarding time and enforces conventions at scale as the contributor base grows.
  • Consequence: Institutional knowledge is now split between human docs and machine-readable skill files, requiring both to be kept in sync.

Traps & gotchas

1. The license is fair-code (Sustainable Use License), NOT MIT/Apache — commercial use in a SaaS product requires an enterprise license. 2. pnpm is required (not npm or yarn) — the monorepo workspaces are configured specifically for pnpm. 3. The .devcontainer/docker-compose.yml likely expects specific environment variables (DB credentials, encryption key N8N_ENCRYPTION_KEY) — missing these causes silent failures at startup. 4. The --experimental-test-module-mocks flag in the test script requires a recent Node.js version; older Node will fail. 5. HCL files suggest Terraform infrastructure that must be provisioned separately for production deployments.

Architecture

Concepts to learn

• Fair-code License — n8n uses the Sustainable Use License, not a standard OSI open-source license — contributors and deployers must understand what commercial use is restricted before embedding n8n in products.
• LangChain.js Agent Executor — n8n's AI nodes are built on LangChain.js agent/tool abstractions — understanding how agents loop over tools is essential for modifying or extending AI workflow nodes.
• Node-based Dataflow Programming — n8n's core execution model is a directed acyclic graph of nodes passing JSON item arrays — understanding dataflow vs. control-flow programming explains why nodes are stateless and how data passes between them.
• Webhook-triggered Workflow Execution — Many n8n workflows are triggered by inbound HTTP webhooks — the platform registers dynamic webhook routes at runtime, which is a non-obvious architectural pattern affecting how workflows start.
• Model Context Protocol (MCP) — The .claude/plugins/n8n/skills/setup-mcps/SKILL.md references MCP, Anthropic's protocol for giving AI models structured access to tools — relevant for the AI-assisted development toolchain in this repo.
• Conventional Commits + Semantic Versioning — The workflow-scripts package uses conventional-changelog and semver to automate changelogs and releases — all commit messages must follow the conventional commits spec or release automation breaks.
• TypeORM Entity Mapping — n8n persists workflows, credentials, and execution history via TypeORM — database schema changes require migrations, and understanding TypeORM's entity/repository pattern is required for any persistence layer work.

Related repos

• zapier/zapier-platform — Direct commercial alternative — the SDK for building Zapier integrations, useful for comparing node/integration authoring patterns.
• activepieces/activepieces — Open-source Zapier alternative in the same space as n8n, built with TypeScript/Angular, useful for architectural comparison.
• n8n-io/n8n-nodes-langchain — Companion repo containing the LangChain AI agent nodes referenced in n8n's native AI capabilities.
• temporalio/temporal — Workflow orchestration engine that solves a related problem (durable execution) at a lower level — understanding it clarifies n8n's design tradeoffs.
• n8n-io/n8n-docs — Official documentation repo — contributors changing node behavior or APIs must update docs here in parallel.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for .github/actions/ci-filter logic beyond existing tests/ci-filter.test.ts

The ci-filter action (ci-filter.mjs) already has a test file but the action itself drives which CI jobs run based on changed files — a critical path. Expanding test coverage to cover edge cases like monorepo cross-package changes, glob pattern conflicts, and the interaction with minimatch/glob (both listed as deps) would prevent costly CI regressions where PRs silently skip required checks.

• [ ] Read .github/actions/ci-filter/ci-filter.mjs and .github/actions/ci-filter/action.yml to map all branching logic
• [ ] Open .github/actions/ci-filter/tests/ci-filter.test.ts and identify untested code paths (e.g. fallback behavior when no patterns match, handling of deleted files, multiple changed packages)
• [ ] Add test cases using the existing Node --experimental-test-module-mocks harness (per package.json test script) for each uncovered branch
• [ ] Add edge-case tests for minimatch glob patterns that span packages (e.g. packages/nodes-base/** vs packages/core/**)
• [ ] Run node --test --experimental-test-module-mocks .github/actions/ci-filter/__tests__/ci-filter.test.ts locally to confirm all new tests pass
• [ ] Submit PR with a description linking each new test to the specific logic branch it covers

Create a SKILL.md for the 'node-add-oauth' skill with a worked end-to-end example referencing real n8n node files

The .claude/plugins/n8n/skills/node-add-oauth/SKILL.md file exists but, given the pattern of other skills (create-community-node-lint-rule has both SKILL.md and reference.md), the OAuth skill is missing a concrete reference document. Adding OAuth2 is one of the most common and error-prone contributions to n8n nodes, and a detailed reference with a real node example (e.g. pointing to an existing node in packages/nodes-base that implements OAuth2) would dramatically reduce incorrect community PRs.

• [ ] Read .claude/plugins/n8n/skills/node-add-oauth/SKILL.md to understand current content and gaps
• [ ] Study .claude/plugins/n8n/skills/create-community-node-lint-rule/reference.md as the template pattern for a companion reference doc
• [ ] Identify 1-2 existing nodes in packages/nodes-base that implement OAuth2 (both Authorization Code and Client Credentials flows) to use as canonical examples
• [ ] Create .claude/plugins/n8n/skills/node-add-oauth/reference.md with: credential file structure, required OAuth2 fields, callback URL registration pattern, token refresh handling, and a diff-style before/after snippet
• [ ] Update SKILL.md to link to the new reference.md and add a step-by-step checklist mirroring the conventions in other SKILL.md files
• [ ] Open a PR explaining that this unblocks community contributors trying to add OAuth to new nodes

Add a GitHub Actions workflow to validate .claude/plugins/n8n/skills SKILL.md files for required sections on every PR

The repo has a sophisticated agent/skill system under .claude/plugins/n8n/skills/ with many SKILL.md files (conventions, content-design, create-pr, protect-endpoints, etc.). There is no automated check that new or modified SKILL.md files contain required sections (e.g. a checklist, a description, references). Without this, contributed skills can be incomplete and silently merged. A lightweight GitHub Action using the existing yaml and glob dependencies already in workflow-scripts/package.json can enforce a schema.

• [ ] Audit all existing .claude/plugins/n8n/skills/*/SKILL.md files to identify the common required sections (e.g. ## Overview, ## Steps, ## References or equivalent)
• [ ] Write a validation script

Good first issues

1. Add test coverage to workflow-scripts quality checks (./quality/*.test.mjs) — the test runner is already wired up but coverage of edge cases in changelog/semver scripts is likely thin. 2. Improve documentation for the .claude/plugins/n8n/skills/setup-mcps/SKILL.md — MCP (Model Context Protocol) integration is new and the skill file likely lacks real usage examples. 3. Add a lint rule (following .claude/plugins/n8n/skills/create-community-node-lint-rule/reference.md) to enforce that all new integration nodes include a credentials test method, which is a common omission in community-contributed nodes.

Top contributors

• @Cadiac — 9 commits
• @aalises — 7 commits
• @heymynameisrob — 7 commits
• @afitzek — 5 commits
• @BGZStephen — 5 commits

Recent commits

• b41f1a0 — fix(core): Defer Instance AI temporary workflow cleanup (no-changelog) (#29700) (OlegIvaniv)
• 17b1206 — refactor(editor): Add executionData store for per-execution state (no-changelog) (#29687) (alexgrozav)
• b72bd19 — fix(DeepL Node): Update credentials to use header-based authentication (#24614) (moseoh)
• 4b9e975 — feat(editor): Surface cluster information in debug data (no-changelog) (#29583) (afitzek)
• ad7cdcc — feat(core): Add JWE decryption to OAuth2 credential flow (#29497) (guillaumejacquart)
• 568e5a2 — fix(core): Isolate expressions on chat resumption and test webhook deactivation (#29703) (ivov)
• 96fabba — feat(instance-ai): Reuse workflow builder sandboxes (no-changelog) (#29598) (OlegIvaniv)
• 63d59d4 — fix(core): Wrap web-search snippets in untrusted data boundaries (no-changelog) (#29695) (Cadiac)
• dad4231 — fix(core): Make MCP client registration cap tunable and surface a proper limit error (#29429) (RicardoE105)
• dc6bd68 — fix(core): Accept placeholder() inside node credentials slot (#29691) (mutdmour)

Security observations

• Medium · Unpinned YAML Dependency Version — package.json (workflow-scripts). The 'yaml' package in package.json uses a caret range specifier (^2.8.3), allowing automatic minor and patch updates. This could introduce unvetted code changes if a compromised or malicious version is published to npm that satisfies the range constraint. Fix: Pin the yaml dependency to an exact version (e.g., '2.8.3' without the caret) and use a lockfile (package-lock.json or yarn.lock) to ensure reproducible builds. Regularly audit dependencies with 'npm audit'.
• Medium · GitHub Actions Unpinned Action Policy Risk — .github/poutine-rules/unpinned_action.rego, .github/actions/*. The presence of a custom poutine rule for unpinned actions (.github/poutine-rules/unpinned_action.rego) suggests this is a known concern in the repository. If GitHub Actions workflows use mutable tags (e.g., @v3) instead of pinned SHA hashes, a compromised action could execute arbitrary code in the CI/CD pipeline with access to secrets and tokens. Fix: Pin all GitHub Actions to specific commit SHAs (e.g., actions/checkout@abc1234) rather than mutable version tags. The existing poutine rule is a good detection mechanism; ensure it is enforced as a blocking check in CI.
• Medium · Potential Secret Exposure via Claude AI Integration — .claude/settings.json, .github/scripts/claude-task/prepare-claude-prompt.mjs, .github/scripts/claude-task/resume-callback.mjs. The repository contains extensive Claude AI plugin configurations, scripts, and agent definitions (.claude/plugins, .claude/settings.json, .github/scripts/claude-task/). These scripts interact with external AI APIs and likely handle API keys or tokens. If secrets are embedded in script files or settings.json, or if the resume-callback.mjs script handles webhook tokens insecurely, credentials could be exposed. Fix: Ensure all API keys and tokens are sourced exclusively from environment variables or GitHub Secrets, never hardcoded. Audit .claude/settings.json and all .mjs scripts for embedded credentials. Add these files to secret scanning rules.
• Medium · Sensitive Workflow Automation Scripts with Broad GitHub API Access — .github/scripts/bump-versions.mjs, .github/scripts/cleanup-ghcr-images.mjs. The workflow-scripts package depends on '@actions/github' and '@octokit/core', which are used to interact with the GitHub API. The bump-versions.mjs and cleanup-ghcr-images.mjs scripts likely use GITHUB_TOKEN or PAT tokens. If these scripts have overly broad token scopes or if tokens are mishandled, it could lead to unauthorized repository or registry access. Fix: Apply the principle of least privilege to all GitHub tokens used by workflow scripts. Use fine-grained personal access tokens with minimal required permissions. Audit token scopes and ensure they are stored only in GitHub Secrets.
• Low · Debug Package Included in Production Dependencies — package.json (workflow-scripts) - dependencies.debug. The 'debug' package (v4.4.3) is listed as a runtime dependency rather than a devDependency. While not directly a vulnerability, debug output could inadvertently log sensitive information (tokens, credentials, request data) if DEBUG environment variables are set in production environments. Fix: Move the 'debug' package to devDependencies if it is only used during development/testing. If required at runtime, ensure DEBUG environment variables are never set in production and that debug output does not include sensitive data.
• Low · Docker Compose Files Potentially Expose Internal Services — .github/docker-compose.yml, .devcontainer/docker-compose.yml. Multiple docker-compose files exist (.github/docker-compose.yml, .devcontainer/docker-compose.yml). Without reviewing their contents, there is a risk that services may bind to 0.0.0.0 (all interfaces) rather than localhost, expose unnecessary ports, or run containers with elevated privileges. This is particularly relevant for CI and devcontainer environments. Fix: Ensure all docker-compose service ports are bound to 127.0.0.1 where external access is not required. Avoid running containers as root. Use specific image digests rather than mutable tags. Review for exposed management ports (e.g., database ports,

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.