> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/administer/environments/promote-changes.md).

# Promote changes

Promote changes from a project or from a whole n8n instance to the environment the instance promotes changes to.

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.

{% hint style="info" %}
**Preview status**

Environments are in Preview and may change in future releases. Try them on test instances before you set them up for your production instances.
{% endhint %}

Before you start, add the environment this instance promotes changes to. See [Plan your environments](https://docs.n8n.io/administer/environments/plan-your-environments.md).

## Project promote

A project promote sends the changes you select from one team project.

1. Open a team project. Next to the project name, a badge with an up arrow shows the number of changes to promote.
2. Select the badge. The **Changes to promote** page opens.
3. Select the workflows to promote. n8n includes their dependencies, such as credentials, variables, data tables, and tags.
4. 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.
5. Select **Promote N changes**.
6. Optional: enter a **Commit message**. If you leave it empty, n8n generates one.
7. 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](https://docs.n8n.io/administer/environments/known-limitations.md#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.

1. Go to **Settings** > **Environments**.
2. On the environment under **Promote changes to**, select **Promote**.
3. Optional: enter a **Commit message**. If you leave it empty, n8n generates one.
4. 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](https://docs.n8n.io/administer/environments/promotion-reviews.md).

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](https://docs.n8n.io/administer/environments/known-limitations.md#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](https://docs.n8n.io/administer/environments/known-limitations.md#personal-projects).

## Related resources

* [Environments](https://docs.n8n.io/administer/environments.md)
* [Plan your environments](https://docs.n8n.io/administer/environments/plan-your-environments.md)
* [Your first promotion](https://docs.n8n.io/administer/environments/first-promotion.md)
* [Apply changes](https://docs.n8n.io/administer/environments/apply-changes.md)
* [Promotion reviews](https://docs.n8n.io/administer/environments/promotion-reviews.md)
* [Git-based promotion](https://docs.n8n.io/administer/environments/git-based-promotion.md)
* [Known limitations](https://docs.n8n.io/administer/environments/known-limitations.md)
* [Upgrade from Environments (Classic)](https://docs.n8n.io/administer/environments/upgrade-from-environments-classic.md)
