# Promoting Environments

## Overview

Promotion creates a new environment in another collection using the exact blueprint version and inputs from a completed run. This enables controlled progression between collections when you want to carry proven configuration forward without rebuilding it from scratch (for example, *dev* to *staging* to *production*).

<figure><img src="/files/TMU0SLDVzlA1rqqvceJT" alt=""><figcaption></figcaption></figure>

## How promotion works

Promotion creates a new [environment](/docs/orchestration/environments.md) in a different [collection](/docs/orchestration/collections.md) using the configuration from a specific completed run.

It helps to think of promotion as copying the **run configuration**, not the environment itself. The blueprint version and inputs move forward, while collection-specific settings are resolved from the target collection.

<details>

<summary>Example: Promoting from Staging to Production</summary>

Your team deploys a `web-app` blueprint into the **Dev** collection.

* Blueprint version: `v1.4.2`
* Inputs:
  * `instance_count = 3`
  * `enable_monitoring = true`
  * `domain_name = dev.example.com`

The run completes successfully and is validated by QA.

You now want to deploy the same configuration to **Staging**.

Instead of manually selecting `v1.4.2` again and re-entering all inputs, you click **Promote** on the selected run and choose your **Staging** collection.

You’re redirected to a new environment run in the Staging collection with:

* Blueprint version `v1.4.2`
* All input values prefilled

You can update what is environment-specific (for example, change `domain_name` to `staging.example.com`). The environment will automatically use the Staging collection’s properties, secrets, connected cloud accounts, and policies.

Then click **Deploy**.

The result:

* A new Staging environment
* The same validated configuration
* No copied state or resources from Dev
* Staging collection policies applied automatically

</details>

The sections below explain what is copied and what is automatically adjusted.

### What promotion copies

Promotion copies the **configuration** from one specific completed run.

That means:

* The same **blueprint version**
* The same **input values**
* The same configuration that was executed in that run

When you promote, Bluebricks opens the **Deploy** page for the target collection with that configuration already filled in. You do not need to reselect the blueprint or re-enter inputs.

Promotion copies configuration only. It does **not** copy: run history, outputs, state files, or existing cloud resources.

The result is a new environment in the target collection that starts fresh but uses the same setup.

### What adjusts automatically

Collection-level settings are **not** copied from the source collection.

Instead, the new environment uses the configuration of the **target collection**, including:

* Collection properties
* Secrets
* Connected cloud accounts
* Policies (such as Owner Approval or Cost Limits)

You do not need to reconfigure properties or secrets during promotion because promotion does not change them. However, the collection you are promoting into must already have the required properties and secrets defined.

## How to promote an environment

**Prerequisites**:

* An existing [environment](/docs/orchestration/environments/creating-environments.md) with at least one successful (completed) run
* Access to both the source and target collections
* At least one [cloud account](/docs/getting-started/connect-your-cloud.md) connected to the target collection

{% stepper %}
{% step %}
**Open the source environment**

1. Navigate to the environment you want to promote:
   1. You can do this from the environment's **Run history** or from the **Graph view**
2. From the three dot-menu, click **Promote** and the promote dialog opens

{% hint style="warning" %}
Make sure you are promoting from the run whose configuration you want to replicate.
{% endhint %}
{% endstep %}

{% step %}
**Select a target collection**

The dialog lists all available collections except the current one. Collections without connected cloud accounts are filtered out.

1. Select the collection you want to promote into
2. Name the new environment
   {% endstep %}

{% step %}
**Review and deploy**

Bluebricks redirects you to the **Deploy** page with the selected run's configuration prefilled.

1. Review the configuration and adjust any values needed for the target collection
2. Click **Deploy**

If the target collection has an Owner Approval or Cost Limit policy configured, those checks apply before the run executes. Learn more about environments
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Promotion is also useful for temporary scaling workflows. You can test a configuration change in staging and promote only the validated result to production. See [Temporary Scaling](/docs/managing-infrastructure/managing-infrastructure/temporary-scaling.md) for the full workflow.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bluebricks.co/docs/orchestration/runs/promoting-environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.