> 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/apply-changes.md).

# Apply changes

Apply changes from an environment to a project or to a whole n8n instance, resolve blockers, and see how Apply affects the instance.

Applying changes brings your work from an environment into your instance. A project apply brings selected changes into one team project. An instance apply makes the whole instance match the environment.

{% 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 applies changes from. See [Plan your environments](https://docs.n8n.io/administer/environments/plan-your-environments.md).

## Add missing projects

A project apply needs the project on the instance. If the environment's branch holds team projects that aren't on this instance yet, add them first:

1. Go to **Settings** > **Environments**.
2. On the environment under **Apply changes from**, select **Add N missing projects**, next to **Apply**.
3. Select the projects to add. Optional: under **Assign a project admin**, select a user for each project.
4. Confirm **Add N missing projects**.

n8n creates the projects empty, with the source's ID, name, icon, and description. It applies no content. If a project has workflows on the branch, open it and run a [project apply](#project-apply).

Don't create these projects by hand. A project you create by hand gets a different ID, so Apply doesn't match it, even when the names match, and the project still shows as missing.

## Project apply

A project apply brings the changes you select into one team project. The project must exist on the instance with the source's ID. See [Add missing projects](#add-missing-projects). A project apply never deletes projects. All projects on an instance share tags, so a tag rename applies in every project.

1. Open a team project. Next to the project name, a badge with a down arrow shows the number of incoming changes.
2. Select the badge. The **Changes to apply** page opens.
3. Select the workflows to apply. 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 this instance and **After** is the environment's branch.
5. Check the **Blockers** tab and resolve any blockers. See [Resolve blockers](#resolve-blockers).
6. Select **Apply N changes**, then confirm.

## Resolve blockers

Before Apply writes anything, n8n checks the changes against the instance. This happens for both project and instance applies. A blocker stops Apply until you resolve it, and Apply changes nothing while blockers remain.

| Blocker                            | What to do                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Missing** credential or variable | Select **Add credential** or **Add variable** and create it. For a credential, n8n pre-fills the fields that use expressions on the source. For a variable, n8n pre-fills the value from the source. A credential owned by another project shows as a conflict instead. See [Cross-project dependencies](https://docs.n8n.io/administer/environments/known-limitations.md#cross-project-dependencies). |
| **No access**                      | The credential exists, but the project can't use it. Ask an admin to share it with the project.                                                                                                                                                                                                                                                                                                        |
| **Conflict**                       | The resource differs on the instance in a way Apply can't fix. Follow the message, then refresh.                                                                                                                                                                                                                                                                                                       |
| **Moved**                          | The workflow or folder is in another project on the branch. A project apply can't move items between projects. Move it on the instance to match the branch, or run an instance apply.                                                                                                                                                                                                                  |

## Confirm destructive changes

Apply asks you to confirm before it:

* Removes or retypes data table columns. This deletes the values in those columns. Rows and other columns stay.
* Deletes projects, in an instance apply.

## Instance apply

{% hint style="danger" %}
An instance apply overwrites every project to match the environment's branch. It deletes projects and content that aren't on the branch. You can't undo this. Only run it after an instance promote from the source, or after you back up the instance.
{% endhint %}

Use an instance apply to bring an instance fully in line with its environment, for example to seed a new production instance. For day-to-day changes, n8n recommends a project apply, which gives you finer control.

1. Go to **Settings** > **Environments**.
2. On the environment under **Apply changes from**, select **Apply**.
3. Read the warning and select **Apply**.
4. If n8n finds blockers or destructive changes, it opens a dialog. Resolve the blockers, review the changes, and confirm. To delete projects that aren't on the branch, confirm **Delete N projects and apply**.

## What Apply changes on the instance

Apply brings over the structure of your work, such as workflows, folders, and data table schemas. It doesn't bring over stored content, such as literal credential secrets or data table rows. Agents aren't included yet.

| Resource    | What Apply does                                                                                                                                                                                                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Projects    | An instance apply creates projects that are on the branch and, after you confirm, deletes projects that aren't. A project apply never creates or deletes projects. To add projects that are missing, see [Add missing projects](#add-missing-projects).                                                  |
| Folders     | Creates, renames, and moves folders within a project to match the branch. A project apply only changes folders that hold a selected workflow.                                                                                                                                                            |
| Workflows   | Creates or updates them. If you deleted a workflow on the source, Apply deletes it on the instance instead of archiving it. An archived workflow stays archived. Apply doesn't change whether a workflow is published. Workflows that Apply creates arrive unpublished, so publish them on the instance. |
| Credentials | Links workflows to the credential with the same ID. If it's missing, you create it while you resolve blockers. If it exists and belongs to the project, Apply updates its name and the fields that use expressions, and keeps every other value, such as secrets.                                        |
| Variables   | The variable must exist on the instance, or you create it while you resolve blockers, with the value from the source pre-filled. Apply never changes the value of an existing variable.                                                                                                                  |
| Data tables | Creates tables or updates their schema. Existing rows stay. Removing or retyping a column deletes only that column's values, after you confirm.                                                                                                                                                          |
| Tags        | Creates tags and renames them to match the branch. Apply never deletes tags.                                                                                                                                                                                                                             |

Apply matches content on the instance like this:

* **By ID:** projects, workflows, credentials, and data tables.
* **By name and scope:** variables.
* **By ID, then by name:** tags.

Promote and apply use [n8n packages](https://docs.n8n.io/build/manage-workflows/n8n-packages.md) to export and import this content.

## If Apply stops

### The branch changed

If someone changes the environment's branch after you load the changes, Apply stops before it writes anything. A project apply shows **The branch changed after the page loaded, so Apply didn't change anything.** An instance apply shows **Apply paused**. Check the latest changes, then apply again.

### Couldn't apply

If an instance apply fails, n8n shows **Couldn't apply to the instance** and **Some changes may already be applied**. n8n doesn't roll back the changes it already made. Apply makes the instance match the branch, so you can run it again to finish.

If a project apply fails, n8n shows **Couldn't apply the changes** and one of these:

* **Nothing changed:** fix the cause in the message, then try again.
* **The request may have run:** the page now shows the latest changes. Check them before you apply again.

## 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)
* [Promote changes](https://docs.n8n.io/administer/environments/promote-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)
