Promote changes
Promote sends workflows and their dependencies from your instance to the environment you promote to. You can promote selected workflows from one project, or every project on the instance.
Before you start, add the environment this instance promotes changes to. See Plan your environments.
Project promote
A project promote sends the changes you select from one team project.
Open a team project. Next to the project name, a badge with an up arrow shows the number of changes to promote.
Select the badge. The Changes to promote page opens.
Select the workflows to promote. n8n includes their dependencies, such as credentials, variables, data tables, and tags.
Inspect the changes. Each resource shows what changed, such as New, Modified, Renamed, Moved, Archived, or Deleted. To compare a workflow visually, select Show diff. The diff viewer shows the canvas Before and After, where Before is the environment's branch and After is this instance.
Select Promote N changes.
Optional: enter a Commit message. If you leave it empty, n8n generates one.
Select Promote.
If you edit a workflow while the page is open, select Refresh before you promote so the page shows your latest changes.
Sub-workflows from other projects are only referenced, not included, so they must already exist on the target instance. See Cross-project dependencies.
n8n never writes credential secrets, data table rows, or executions to the repository. Credentials travel as their ID, name, type, and the fields that use expressions. Variables travel with their values. A variable is only a name and a value, so unlike a credential it has no secret part that n8n could leave out. Keep secrets in credentials, not in variables.
Promoting a workflow marked Deleted removes it from the branch, and applying deletes it on the target instance. An archived workflow stays archived.
Instance promote
An instance promote sends every team project and overwrites the project content on the branch to match the instance. Personal projects aren't included.
Go to Settings > Environments.
On the environment under Promote changes to, select Promote.
Optional: enter a Commit message. If you leave it empty, n8n generates one.
Select Promote.
Where the changes go
The environment's settings decide what n8n does with the changes:
Direct: n8n commits to the environment's branch.
Feature branch: n8n pushes a feature branch named
n8n-promotion/<timestamp>, based on the environment's branch. Someone merges it on the Git host.Feature branch with a promotion review: n8n also opens a promotion review. With GitLab, that's a merge request. See Promotion reviews.
n8n sets the commit author to your n8n name and email. The Git host records the push and any merge request under the provider's account or token.
What blocks a promote
Workflows or folders moved to another project
A project promote can't move workflows or folders between projects. n8n names the item and both projects. Use an instance promote instead. Moves within a project work, and moves into a personal project aren't supported. See Moving workflows and folders between projects.
Workflows in personal projects
An instance promote fails if a workflow references a workflow in a personal project, such as a sub-workflow or error workflow. n8n shows workflow dependencies not included in the package. Export aborted. Move the referenced workflow into a team project, or remove the reference, then promote again. See Personal projects.
Related resources
Last updated
Was this helpful?