Database Schema & Migrations
Relevant source files
The following files were used as context for generating this wiki page:
Projects are a core organizational feature in n8n, designed to provide resource isolation, access control, and collaboration for teams. They function as containers for key n8n resources, including Workflows, Credentials, Folders, and Data Tables, allowing for granular permission management and a structured multi-user environment. This feature is essential for team-based and enterprise deployments where different users and groups require access to specific sets of automation resources.
The project system is enabled through feature flags such as sharing, folders, advancedPermissions, and various projectRole flags. It distinguishes between "Personal" spaces and "Team" projects, each with its own set of members and resources.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:13-19, packages/frontend/@n8n/i18n/src/locales/en.json:1159-1160,1202-1203
Core Concepts
Projects serve as the primary mechanism for organizing and securing resources within an n8n instance.
- Resource Scoping: Workflows, Credentials, and other assets created within a project are scoped to that project. This means they are not visible or accessible from other projects unless explicitly shared.
- Collaboration: Projects allow multiple users to collaborate by assigning them roles with specific permissions.
- Types: The system supports
personalandteamproject types, enabling a distinction between an individual's private workspace and a collaborative team environment.
Sources: packages/@n8n/api-types/src/schemas/tests/project.schema.test.ts:22-26, packages/testing/playwright/tests/ui/39-projects.spec.ts:30-41
Entity Relationship Diagram
The diagram below illustrates the relationships between Projects and other key entities like Users, Workflows, and Credentials.
This diagram shows how Projects contain Workflows and Credentials, and how Users are linked to Projects through specific roles.
Sources: packages/@n8n/api-types/src/schemas/tests/project.schema.test.ts:79-83, packages/testing/playwright/tests/ui/39-projects.spec.ts:30-41
Data Model and Schema
The project entity is defined with specific attributes and validation rules to ensure data integrity. The schema is validated using Zod.
Sources: packages/@n8n/api-types/src/schemas/tests/project.schema.test.ts
Project Fields
| Field | Type | Constraints | Description |
|---|---|---|---|
name | string | 1..255 characters | The name of the project. |
type | enum | Must be personal or team. | The type of the project. |
icon | object | `{ type: 'emoji' | 'icon', value: string }` |
description | string | 0..512 characters (optional) | A brief description of the project's purpose. |
Sources: packages/@n8n/api-types/src/schemas/tests/project.schema.test.ts:8-76
Project Relation Schema
User access to projects is managed through a relation that links a user ID with a project and a specific role.
| Field | Type | Constraints | Description |
|---|---|---|---|
userId | string | Required, must be a string. | The ID of the user being granted access. |
role | string | Must be a valid role (e.g., project:admin). | The role assigned to the user for this project. |
Sources: packages/@n8n/api-types/src/schemas/tests/project.schema.test.ts:78-107
User Roles and Permissions
Projects use a role-based access control (RBAC) system to manage what users can do within a project. The primary roles are Admin, Editor, and Viewer.
| Role | Permissions Summary |
|---|---|
| Admin | Full control. Can edit project settings, manage users, and has full CRUD permissions on all project resources. |
| Editor | Can create and edit resources like workflows and credentials but cannot manage project settings or users. |
| Viewer | Read-only access. Can view workflows and executions but cannot make any changes. |
Sources: packages/frontend/@n8n/i18n/src/locales/en.json:1174-1176, packages/testing/playwright/tests/ui/39-projects.spec.ts:79-83
A more granular breakdown of permissions is available for different resource types within a project:
| Resource | Permission | Description |
|---|---|---|
| Project | read | View project name, icon, description, and navigate within the project. |
update | Edit project details and manage users. | |
delete | Delete the entire project and all its contents. | |
| Folder | read | View folders and subfolders within a project. |
update | Rename folders, move workflows between folders, and change parent folder. | |
create | Create new folders or subfolders. | |
delete | Delete an empty folder. | |
| Workflow | read | View workflows within the project. |
execute | Execute workflows. | |
update | Edit workflow content, activate/deactivate, and execute workflows. | |
create | Create new workflows. | |
move | Transfer workflows to another project. | |
delete | Delete workflows. | |
| Credential | read | View credentials details (secret masked) and use them in workflows. |
update | Edit credential details including secret. | |
create | Create new credentials. | |
move | Move credentials to another project. | |
delete | Delete credentials. |
Sources: packages/frontend/@n8n/i18n/src/locales/en.json:1126-1158
Key Operations and Flows
Project Creation
Creating a project involves a UI interaction that triggers an API call to the backend, resulting in a new project record in the database.
The following diagram shows the sequence of creating a project.
This sequence is derived from the ProjectComposer.createProject helper used in E2E tests, which simulates the user flow for creating a new project.
Sources: packages/testing/playwright/CONTRIBUTING.md:129-144, packages/testing/playwright/tests/ui/39-projects.spec.ts:28-41
Resource Management
Projects provide a robust framework for managing resources, including creation, filtering, and moving them between different scopes.
Resource Creation and Scoping
When a resource like a credential or workflow is created, it is associated with the currently active project. For example, creating a credential from within a project's context will automatically assign it to that project, making it available only to that project's members.
The E2E tests demonstrate this by creating a project, adding a credential to it, and then verifying that the credential is only listed for that specific project and not for others.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:28-41
Moving Resources Between Projects
Users with appropriate permissions can move workflows and credentials between projects or between a project and a personal space. This is typically done via a "Move" action in the UI, which opens a modal to select the target project or user.
The flow for moving a resource is as follows:
This flow is based on the test cases should move the workflow to expected projects and should move the credential to expected projects.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:188-267, packages/frontend/@n8n/i18n/src/locales/en.json:1342-1358
Project Settings
Each project has a dedicated settings page where administrators can manage its details.
- Icon and Name: The project's name and icon can be customized. Icons can be selected from a predefined list or from emojis.
- Members: Project admins can add or remove users from the project and assign them roles (
Admin,Editor,Viewer). - Danger Zone: This section contains critical actions like deleting the project. When deleting, the user is prompted to either wipe all associated data or transfer it to another project.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:148-169, packages/frontend/@n8n/i18n/src/locales/en.json:1229-1262
Testing Projects
The "Projects" feature is extensively tested using Playwright for end-to-end (E2E) scenarios. The testing architecture relies on a ProjectComposer class, which encapsulates common business workflows related to project management.
This approach allows tests to be readable and focused on the business logic, abstracting away the low-level UI interactions.
Sources: packages/testing/playwright/CONTRIBUTING.md:128-144, packages/testing/playwright/tests/ui/39-projects.spec.ts
A typical test case for a project-related feature looks like this:
// From: packages/testing/playwright/tests/ui/39-projects.spec.ts
test('should filter credentials by project ID when creating new workflow or hard reloading an opened workflow', async ({
n8n,
}) => {
const { projectName, projectId } = await n8n.projectComposer.createProject();
await n8n.projectComposer.addCredentialToProject(
projectName,
'Notion API',
'apiKey',
NOTION_API_KEY,
);
const credentials = await n8n.api.credentials.getCredentialsByProject(projectId);
expect(credentials).toHaveLength(1);
const { projectId: project2Id } = await n8n.projectComposer.createProject();
const credentials2 = await n8n.api.credentials.getCredentialsByProject(project2Id);
expect(credentials2).toHaveLength(0);
});
This test demonstrates creating a project, adding a credential, and then asserting that the credential is correctly scoped to that project.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:28-41
Summary
The Projects feature is a cornerstone of n8n's multi-user and collaborative capabilities. It provides a structured way to organize, isolate, and share automation resources like workflows and credentials. Through a system of roles and permissions, projects enable secure collaboration within teams. The entire feature is backed by a clear data model and is thoroughly validated with a comprehensive suite of end-to-end tests, ensuring its reliability and stability.