n8n source control and environments

Start with the branch model, because it decides how changes reach production and how easily they can be reversed. A common pattern runs one n8n instance per environment: development, staging and production. Each instance is tied either to its own branch or to a deliberate promotion path in which a change moves forward through gates you define. For example (illustrative), a team might keep develop, staging and main branches, with the development instance reading develop, the staging instance reading staging and the production instance reading main. Another team might keep a single main branch and promote by tag. Both can work, but they produce different review histories and different rollback steps, so choose the model before the first production workflow is built.

The model shapes review. When each environment reads its own long-lived branch, promotion is a merge between branches, and the diff between branches shows what staging has that production does not yet have. That is useful for audit, but branches can drift if a hotfix lands in production and never returns to development. A single-branch model with tags keeps one history and makes each promoted version a fixed point, but reviewers then depend on tag discipline and on your own record of which workflows changed. For rollback, ask what reverting means in each model: reverting a commit, redeploying an earlier tag, or restoring a workflow to an earlier state inside n8n. These actions affect running executions, scheduled triggers and credentials differently, so test each one.

Several details must come from n8n's documentation before you design around them, because the material available to you does not settle them. First, confirm which branch each instance reads and where that setting lives, including whether it can change without redeploying the instance. Second, confirm whether promotion is a merge performed in Git, a pull initiated from within the target instance, or a push from development, and who is allowed to trigger it. Third, confirm how deleted workflows are handled: whether deleting a workflow in development removes it from the branch, whether a pull removes it from staging or production, and what happens to webhooks, schedules and executions that depend on it. Record each answer with the n8n version you tested, since behavior can change between releases.

Test these answers in a sandbox before any production workflow depends on them. Create a throwaway workflow in development, promote it, delete it in development, pull again and observe each step. Repeat once with a change made directly in production so you can see how drift appears and how your team would correct it. Check the plan requirement early: n8n's pricing page lists environments with Git as a Business and Enterprise feature, and it lists the Business plan at 667 euros per month billed annually, currently self-hosted only. Ask any implementation partner to quote the three instances, the Git host, the review process and the promotion runbook as separate lines, so you can see which costs are one-time setup and which recur.

The decision in this section is which people may move workflow changes in each direction: committing from development, pulling into staging, and approving promotion to production. Treat these as three separate permissions. In a self-hosted n8n setup with environments enabled, the person who edits a workflow in development may be a builder who should not also decide when that change reaches customer-facing automations. Write the mapping down before anyone configures Git. For each role, list who may commit, who may pull into staging, who may approve production changes, and who may only read. A useful test is whether every push and pull can be traced to one named person.

Role design matters for audit trails because a production change review depends on answering three questions: who committed the change, who approved it, and whether that approver had the authority to do so. If several people share one admin account, or one role can both commit and approve, the history shows that something happened but not that a control operated. Separation of duties also limits what a single careless or compromised account can do. Ask n8n how the environment history records the acting user for each commit and each pull, and confirm how long those records are retained in your deployment so they match your own evidence requirements.

Role design also prevents accidental overwrites. An environment pull replaces a workflow definition on the target instance, so a pull into staging or production can silently discard a version that someone is still editing there. Decide whether hotfixes made directly in staging or production are allowed at all. If they are, define who must bring those changes back into Git and how quickly. Restrict production pulls to a small group, and require that the source branch is the reviewed one. Also decide how credentials and environment-specific settings are handled during a pull, and confirm the current behavior in n8n's documentation before any production workflow depends on it.

Before the design is final, confirm the exact role names and permission model in the current n8n user management documentation. Then run a walkthrough in a Business trial or with n8n under the contract, using a test Git repository and two non-production instances. Check which actions each role can perform in the environments feature, whether approval is enforced by the product or only by process, and whether your Git host's branch protection rules must be part of the control. The Business plan is the lowest plan listed with environments and Git, so confirm that the roles you need exist at that level. Include the cost of this walkthrough and the recurring review of role assignments when staff change in your quote.

Each n8n instance keeps its own credentials. Those credentials are stored in the database that instance uses, and they are encrypted with the instance's encryption key. When you run separate development, staging and production instances, the first design question is whether those instances should share an encryption key at all. Sharing a key makes it simpler for credentials to be read across instances, but it also means that a leak of the key in one environment exposes the credentials of every environment that uses it. Decide this before the first workflow is promoted, not after. Queue mode changes the picture for production. The n8n queue mode documentation requires the main instance's encryption key to be shared with every worker and webhook processor, because those processes must decrypt credentials stored in the database to run workflows. That means the production key is not confined to the main instance. It is also present on each worker and webhook host, in their configuration and environment. Your threat model and your host access controls should treat every processor as a holder of the production key, and your secret handling should reflect that.

Copying a production encryption key into development is the risk to weigh most carefully. A developer workstation, a shared test server or a development database restored from production backups may then hold the key that protects live credentials to payment, HR or customer systems. Development environments are usually less tightly controlled, and their logs, exports and backups are often copied more freely. If the key leaks, an attacker who obtains the production database dump could decrypt those credentials. A safer pattern is a distinct key per environment, with development and staging using their own credentials pointing at sandbox systems. Illustrative example: a team restores a production database into staging for testing. Unless the key is also changed or the restored credentials are removed, the staging host now protects production secrets with a staging-grade control set. Before you rely on any promotion process, confirm with n8n exactly how credentials move between environments, or whether they move at all. Ask whether credential records are exported with the workflow definition, whether they are exported encrypted, and whether the encryption key is required to import them into another instance. Ask whether a credential reference inside a workflow survives promotion, or whether the target environment must recreate the credential and rebind it. Also confirm how the Git-backed environment feature handles credential data, because a workflow file in a repository should not carry secret values. Turn these answers into a written rule for your team: which key each environment uses, who may read it, where it is stored, how it is rotated, and what must be recreated rather than copied during promotion. Test the rule with a restore drill into a non-production instance before any real credential is involved. Confirm all of this against the current n8n documentation and against your own environment, since the controls available depend on your plan and deployment.