> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Promote assets between environments

> Choose the right method for promoting Itential Platform assets from a development environment to production.

When you build in Itential Platform, you typically work in a development environment, a dedicated instance of the Platform where it's safe to create, test, and iterate. When your assets are ready, you need to move them to other environments, typically staging and then production, each of which is a separate Platform instance.

This movement is called *promotion*. It's directional by design: assets flow from development toward production, never the other way. A customer running two Platform instances (one for development and one for production) has two environments. A customer running three instances has three.

```mermaid
flowchart LR
    A[Development: Build and test here] --> B[Staging: Validate before release] --> C[Production: Live automation runs here]
```

The assets you can promote include:

* Studio Projects, which bundle workflows, forms, transformations, and templates.
* Golden Configurations.
* Lifecycle Manager (LCM) resource models.
* Operations Manager automations.

## Understand your promotion tools

There are three ways to move assets between environments.

* **The Platform UI** is the built-in export and import interface in each Itential Platform application, such as Studio and Operations Manager. You export an asset from the source environment, which downloads it as a file, then import that file into the target environment. No additional tooling is required, but the process is manual and doesn't scale well.

* **`ipctl`** is Itential's open-source command-line tool that you can use to manage assets. Its `copy` command connects directly to two Platform environments and moves assets between them without requiring you to manually download and re-upload files. `ipctl` also supports `export` and `import` commands for git-based workflows. See the [ipctl repository](https://github.com/itential/ipctl) for installation instructions.

* **CI/CD pipelines** automate the entire promotion workflow. Itential provides an [asset repository template](https://github.com/itential/asset-repository-template) with ready-made pipeline definitions that trigger deployments based on git tags, with no manual steps required once configured.

The Platform UI and `ipctl` use different file formats. If you use one method to export an asset, you must use the same method to import it. Mixing the two will cause import failures.

## Choose a promotion method

Your choice depends on whether you have a git repository and whether you need automated deployment.

|                  | Option 1: No git                             | Option 2: Git, no pipeline                  | Option 3: Git + CI/CD                                         |
| ---------------- | -------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
| **Git required** | No                                           | Yes                                         | Yes                                                           |
| **Automation**   | None                                         | None                                        | Full                                                          |
| **Best for**     | Getting started or simple one-off promotions | Version history without CI/CD complexity    | Repeatable, auditable production deployments                  |
| **Tools**        | Platform UI or `ipctl copy`                  | Platform UI or `ipctl export/import`        | Itential pipeline templates                                   |
| **Guide**        | Promote assets without git                   | Promote assets with git, without a pipeline | [Set up Git and CI/CD promotion](./set-up-git-cicd-promotion) |

Itential recommends Option three. Git-based promotion with CI/CD gives you version history, automated validation, consistent deployments, and a clear audit trail for every change that reaches production. Options one and two are valid starting points if your team isn't ready for CI/CD.

If you don't have a git repository, we recommend adopting one. Git gives you version history, a single source of truth for your assets, and a path to automation. See [Set up your git repository](/itential-platform/maintain/asset-promotion/set-up-git-cicd-promotion) for guidance.

## Promote assets in the right order

Assets in Itential Platform reference each other by name. A workflow can call a transformation, use a template, and trigger an Operations Manager automation, all defined as separate assets. If you promote the workflow but not the assets it depends on, the workflow will import successfully but fail at runtime in the target environment.

For example, promoting a "Network Provisioning" workflow without first promoting its "Parse Device Config" transformation means the workflow arrives in production with a broken reference. The import won't warn you. The failure only surfaces when someone runs the workflow.

Promote assets in the following order to ensure every dependency exists before the assets that reference it. Organize your Studio assets into Projects rather than the global space, since ungrouped assets are harder to export and promote.

#### Configure Admin Essentials

Configure the following manually in the target environment. Automated promotion of Admin Essentials is not currently supported.

* **Adapters:** Install and configure required adapters first.
* **Integration Models:**  Import integration models then configure the appropriate integration instances.
* **Users and Groups:** Create necessary users and groups with appropriate permissions.
* **Custom Roles:** Define any custom roles needed for access control.

#### Import Configuration Manager assets

* **Golden Configurations:** Import trees. Reference Golden configuration by name, not by ID. IDs differ across environments.

#### Import Studio assets

* **Projects:** Import in dependency order: projects with no dependencies first, then projects that reference other projects.

Organize assets into Studio Projects rather than the global space. Ungrouped assets are harder to track, export, and promote.

#### Import Operations Manager assets

* **Automations:** Import last. Automations reference workflows and forms that must already exist in the environment, or the import will fail.

#### Import Lifecycle Manager assets

* **LCM Resource Models:** Import resource models and their associated workflows and JSTs.

## Related resources

#### [Organize your asset repository](./organize-asset-repository)

Recommended git repository structure and asset organization strategies

#### [Set up Git and CI/CD promotion](./set-up-git-cicd-promotion)

Configure automated promotion with Itential's pipeline templates