Source Control & Environments
Relevant source files
The following files were used as context for generating this wiki page:
Source Control and Environments is an enterprise-grade feature designed to manage multiple deployments of n8n by synchronizing them through a shared Git repository. This system allows users to maintain consistency across different stages of development, such as development, staging, and production environments.
The primary purpose of this module is to enable versioning, branching, and safe promotion of workflows and configurations. It integrates directly with Git providers (e.g., GitHub, Gitea) using SSH for secure communication and provides a dedicated UI within the n8n settings to manage repository connections and environment-specific preferences.
Sources: packages/cli/src/modules/source-control.ee/README.md:3-5, packages/testing/playwright/tests/e2e/settings/environments/source-control.spec.ts:58-60
System Architecture
The Source Control system operates as an Enterprise Edition (EE) module. It acts as an abstraction layer between the n8n instance and a Git-based version control system. The architecture supports operations such as connecting repositories, switching branches, and managing read-only states for specific environments.
Core Components and Indicators
- Preferences Management: Handles environment-specific settings like the current branch and repository URL.
- Git Integration: Manages the cloning and synchronization of the repository within the n8n instance.
- UI Indicators: A dedicated "Source Control Connected" indicator and specific action buttons (Push/Pull) appear in the sidebar when the feature is active.
Sources: packages/cli/src/modules/source-control.ee/README.md:11-13, packages/testing/playwright/tests/e2e/settings/environments/source-control.spec.ts:88-100
Connection Flow
The connection process involves a secure handshake using SSH keys between the n8n instance and the remote Git provider.
Environment Management
Environments allow for strict control over how changes are applied. A key feature is the "Read-Only" mode, which is typically used for production environments to prevent accidental modifications directly on the server.
Operational Restrictions
| Feature | Standard Mode | Read-Only Mode |
|---|---|---|
| Pull Changes | Enabled | Enabled |
| Push Changes | Enabled | Disabled |
| Direct Edit | Allowed | Restricted/Restricted Push |
In read-only mode, the "Push" button in the sidebar is explicitly disabled to ensure that the environment can only receive updates from the source control repository, maintaining a one-way flow of truth from the Git branch.
Sources: packages/testing/playwright/tests/e2e/settings/environments/source-control.spec.ts:133-145
Branching Logic
Users can switch between different branches (e.g., main, development, staging) through the Environment settings. Switching a branch updates the internal preferences and synchronizes the local instance state with the selected remote branch.
Technical Implementation and API
The module utilizes several internal REST endpoints to manage the lifecycle of the source control connection and environment preferences.
Key API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/rest/source-control/preferences | GET | Retrieves current environment preferences (e.g., current branch). |
/rest/source-control/preferences | PATCH | Updates environment settings such as branch name or read-only mode. |
/rest/source-control/preferences | POST | Initiates a new repository connection. |
/rest/source-control/disconnect | POST | Disconnects the current repository and clears settings. |
Sources: packages/testing/playwright/tests/e2e/settings/environments/source-control.spec.ts:14-55
Development and Testing
For local development, it is recommended to run n8n within a Docker container to isolate Git settings from the host machine.
- Docker Setup:
pnpm --filter n8n-containers stack:enterprise - Test Capabilities: The system uses the
@capability:source-controltag for E2E testing, requiring a licensed instance and a Git service (like Gitea) to verify flows.
Sources: packages/cli/src/modules/source-control.ee/README.md:15-18, packages/testing/playwright/README.md:88-90, packages/testing/playwright/tests/e2e/settings/environments/source-control.spec.ts:60-65
Summary
Source Control & Environments provides the infrastructure necessary for professional CI/CD workflows within n8n. By leveraging Git for synchronization and offering granular controls like read-only environments and branch switching, it ensures that enterprise teams can manage complex automation deployments with high reliability and security.
Sources: packages/cli/src/modules/source-control.ee/README.md:3-5