Source Control (Enterprise)

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/environments.ee/source-control/source-control.service.ee.ts
• packages/cli/src/environments.ee/source-control/source-control.controller.ee.ts
• packages/cli/src/environments.ee/source-control/source-control-git.service.ee.ts
• packages/cli/test/integration/environments/source-control.service.test.ts
• packages/cli/src/environments.ee/source-control/source-control-export.service.ee.ts
• packages/cli/src/environments.ee/source-control/tests/source-control-import.service.ee.test.ts
• packages/frontend/@n8n/i18n/src/locales/en.json
• packages/nodes-base/nodes/Github/Github.node.ts

The Source Control (Enterprise) feature allows for using multiple n8n instances for different environments (e.g., development, production) and deploying changes between them via a Git repository. This system enables versioning of n8n resources like workflows, credentials, tags, and folders, providing a robust mechanism for managing changes and ensuring consistency across environments.

This feature is part of the Enterprise plan and integrates Git functionality directly into the n8n backend and UI. It allows users to push local changes to a remote Git repository and pull changes from the remote to update the local n8n instance. The system is designed with security and permissions in mind, scoping actions and visibility based on user roles.

Sources: packages/frontend/@n8n/i18n/src/locales/en.json:1819-1821

Architecture

The Source Control feature is built upon a set of interconnected services that handle API requests, core business logic, Git operations, and data serialization/deserialization.

The diagram below illustrates the high-level architecture of the Source Control system.

Key Components

Component	Description	Source File -
SourceControlController	Exposes the feature via a REST API. Handles incoming HTTP requests and delegates to SourceControlService.	packages/cli/src/environments.ee/source-control/source-control.controller.ee.ts -
SourceControlService	The core service containing the main business logic for push, pull, and getStatus. It orchestrates other services.	packages/cli/src/environments.ee/source-control/source-control.service.ee.ts -
SourceControlGitService	An abstraction layer for interacting with the Git repository. Handles operations like clone, pull, push, and commit.	packages/cli/src/environments.ee/source-control/source-control-git.service.ee.ts -
SourceControlExportService	Responsible for reading data from the n8n database and writing it to files in the local Git work folder.	packages/cli/src/environments.ee/source-control/source-control-export.service.ee.ts -
SourceControlImportService	Responsible for reading files from the local Git work folder and updating the n8n database.	packages/cli/src/environments.ee/source-control/__tests__/source-control-import.service.ee.test.ts -
SourceControlStatusService	Determines the status of resources (created, modified, deleted) by comparing the local database with the Git repository.	packages/cli/test/integration/environments/source-control.service.test.ts:182 -
SourceControlScopedService	Manages access control and permissions, ensuring users can only see and modify resources within their authorized scope (e.g., projects).	packages/cli/src/environments.ee/source-control/source-control-scoped.service.ts -

API Endpoints

The SourceControlController provides the REST API for all source control operations.

Sources: packages/cli/src/environments.ee/source-control/source-control.controller.ee.ts

Method	Path	Description -
POST	/v1/source-control/status	Retrieves the status of all source-controlled resources, showing differences between the local instance and the remote Git repository. -

• GET | /v1/source-control/preferences | Gets the current source control preferences, such as connection status.
• POST | /v1/source-control/preferences | Updates the source control preferences.
• POST | /v1/source-control/push | Pushes local changes to the remote Git repository.
• POST | /v1/source-control/pull | Pulls remote changes from the Git repository to the local instance.

Git Repository Structure

When using source control, n8n resources are exported into a structured directory layout within the Git repository. This ensures that workflows, credentials, and other configurations are stored in an organized and predictable manner.

Sources: packages/cli/test/integration/environments/source-control.service.test.ts:28-33

.
├── workflows/
│   ├── <workflow_id>.json
│   └── ...
├── credential_stubs/
│   ├── <credential_id>.json
│   └── ...
├── folders.json
└── tags.json

• workflows/: This directory contains individual JSON files for each workflow. The filename is the workflow's ID.
• credential_stubs/: This directory contains JSON files for each credential. These are "stubs" and do not contain sensitive data.
• folders.json: A single JSON file that defines the folder structure for organizing workflows.
• tags.json: A single JSON file containing all tags and their mappings to workflows.

Core Operations

Get Status

The getStatus operation is fundamental to the source control feature. It compares the state of resources in the local n8n database against the files in the Git repository to identify changes.

The process is as follows:

1. Fetch Local State: The service retrieves all relevant local resources (workflows, credentials, folders, tags) from the database that are within the user's authorized scope.
2. Fetch Remote State: It reads all corresponding files from the local Git work folder.
3. Compare: The SourceControlStatusService compares the two sets of data to determine the status of each resource:
   • created: Exists locally but not in Git.
   • deleted: Exists in Git but not locally.
   • modified: Exists in both but has different content (e.g., a different versionId for a workflow).
   • renamed: The resource ID is the same, but the name has changed.

This status information is then used by the UI to show the user what changes can be pushed or pulled.

Sources: packages/cli/src/environments.ee/source-control/source-control.service.ee.ts:114-123, packages/cli/test/integration/environments/source-control.service.test.ts:251-260

Push Operation

The push operation commits and pushes local changes from the n8n instance to the remote Git repository.

This diagram shows the sequence of a push request.

1. A user initiates a push from the UI, selecting which changes to commit.
2. The SourceControlController receives the request and calls pushWorkfolder in the SourceControlService.
3. The SourceControlService validates that the instance is not read-only.
4. It then uses the SourceControlExportService to write the selected local changes (workflows, credentials, etc.) from the database to the corresponding files in the local Git working directory.
5. Finally, it calls the SourceControlGitService to commit the changes with the user-provided message and push them to the remote repository.

Sources: packages/cli/src/environments.ee/source-control/source-control.controller.ee.ts:61-71, packages/cli/src/environments.ee/source-control/source-control.service.ee.ts:157-184, packages/cli/test/integration/environments/source-control.service.test.ts:479-510

Pull Operation

The pull operation fetches changes from the remote Git repository and applies them to the local n8n instance.

This diagram shows the sequence of a pull request.

1. A user initiates a pull from the UI.
2. The SourceControlController receives the request and calls pullWorkfolder in the SourceControlService.
3. The service first calls the SourceControlGitService to pull the latest changes from the remote repository into the local work folder.
4. It then uses the SourceControlImportService to read the changed files and apply them to the n8n database. This can involve creating new workflows, updating existing ones, or deleting ones that were removed from Git.

Sources: packages/cli/src/environments.ee/source-control/source-control.controller.ee.ts:73-81, packages/cli/src/environments.ee/source-control/source-control.service.ee.ts:186-212

Data Models

The feature relies on specific data structures when exporting resources to JSON files.

Exportable Workflow

Workflows are exported with their core properties.

interface ExportableWorkflow {
	id: string;
	name: string;
	connections: object;
	isArchived: boolean;
	nodes: object[];
	owner: RemoteResourceOwner;
	triggerCount: number;
	parentFolderId: string | null;
	versionId: string;
}

Sources: packages/cli/test/integration/environments/source-control.service.test.ts:101-123

Exportable Credential (Stub)

Credentials are exported as "stubs" to avoid committing sensitive information to the Git repository. The actual secret values are stripped out and replaced with empty strings. When these are pulled into another instance, they must be manually re-populated.

interface ExportableCredential {
	id: string;
	data: Record<string, any>; // Sensitive values are cleared
	name: string;
	type: string;
	ownedBy: RemoteResourceOwner;
}

The exportCredentialsToWorkFolder function in SourceControlExportService is responsible for this sanitization. It iterates over the credential data and clears values for fields like clientSecret, apiKey, token, etc., while preserving the structure and non-sensitive fields.

Sources: packages/cli/src/environments.ee/source-control/source-control-export.service.ee.ts:100-128, packages/cli/test/integration/environments/source-control-export.service.test.ts:76-99

Exportable Folder

Folder structures are also version-controlled.

interface ExportableFolder {
	id: string;
	name: string;
	homeProjectId: string;
	parentFolderId: string | null;
	createdAt: string;
	updatedAt: string;
}

Sources: packages/cli/test/integration/environments/source-control.service.test.ts:40-48

Permissions and Scoping

A critical aspect of the Source Control feature is its adherence to n8n's permission model. The SourceControlScopedService ensures that users can only view and interact with resources they have access to.

• A Global Admin or Global Owner can see and push/pull all resources across all projects and personal spaces.
• A Project Admin can only see and interact with resources within the projects they administer. They cannot push changes to workflows or credentials outside their scope.
• A Global Member with no specific project roles typically cannot see or interact with any source-controlled resources.

This is enforced in the getStatus, pushWorkfolder, and pullWorkfolder methods, which all rely on the SourceControlScopedService to filter resources based on the current user's context.

Sources: packages/cli/test/integration/environments/source-control.service.test.ts:326-477, packages/cli/src/environments.ee/source-control/tests/source-control-import.service.ee.test.ts:233-250

GitHub Node Integration

The GitHub node also provides functionality related to source control concepts, such as dispatching a workflow and waiting for its completion. The dispatchAndWait operation uses a webhook resumeUrl to pause the n8n workflow execution until the GitHub Actions workflow calls back to n8n, indicating completion.

Sources: packages/nodes-base/nodes/Github/Github.node.ts:460-496