> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/orchestration-quick-start.md).

# Orchestration Quick Start

This guide walks you through the core Bluebricks orchestration workflow end to end. By the time you finish, you will have a live environment and a reusable blueprint that defines it.

{% hint style="info" %}
**New to Bluebricks?** Start with the [Quick Start](/docs/getting-started/quick-start.md) to connect your cloud and meet the agent. This guide is for teams setting up orchestration workflows.
{% endhint %}

## Before you start

Read the [Orchestration Overview](/docs/orchestration/orchestration.md) to understand how packages, collections, and environments fit together.

You will also need:

* A Bluebricks account with admin-level permissions (sign in at [app.bluebricks.co](https://app.bluebricks.co))
* Access to at least one cloud provider (AWS, GCP, or Azure)
* Infrastructure as Code in a Git repository

## 1. Create a collection and connect a cloud provider

A [collection](/docs/orchestration/collections.md) is the connecting layer between Bluebricks and your cloud provider. It represents a single cloud account, subscription or project that Bluebricks can discover, orchestrate, and manage.

You use collections to define *where* Bluebricks operates.

To create a collection:

{% stepper %}
{% step %}
**Create a collection**

1. Go to the [**Collections**](https://app.bluebricks.co/collections) page in the Bluebricks app
2. Click **Create collection**
3. Enter a name (for example, `dev-quickstart`)
   {% endstep %}

{% step %}
**Connect your cloud provider**

Continuing from the create collection dialog:

1. Select your cloud provider: **AWS**, **GCP**, **Azure**, or **Self-hosted**
2. In Account Number / ID dropdown, click **Create new**
3. Follow the setup steps to grant Bluebricks the necessary permissions
   1. For provider-specific instructions, see [Connect your Cloud](/docs/getting-started/connect-your-cloud.md)
4. Click **Connect & Create**
   {% endstep %}
   {% endstepper %}

## 2. Create an environment

An [environment](/docs/orchestration/environments.md) connects a [blueprint](/docs/orchestration/packages/blueprints-overview.md) to a collection and tracks the full lifecycle of your infrastructure: planning, applying, and tearing down resources.

From the [**Environments**](https://app.bluebricks.co/environments) page, click **Create environment** to get started.

The steps differ depending on your VCS provider. Pick the tab that matches your setup:

{% tabs %}
{% tab title="GitHub" %}
If your IaC code is in a GitHub repository, Bluebricks can connect directly to it. It creates the blueprint for you, and every push to the configured branch triggers a run. Bluebricks posts a plan to every pull request as a GitHub Check Run.

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

Choose the collection you created in step 1.
{% endstep %}

{% step %}
**Set source code**

1. Select your IaC technology (OpenTofu, Terraform, Helm, CloudFormation, or Bicep)
2. Choose how to connect your repository:
   * **From connected repo**: select your GitHub organization and repository from your connected integrations
   * **From remote URL**: enter a Git remote URL manually (for public repositories)
3. Set the branch and, optionally, a subdirectory path

{% hint style="info" %}
Private repositories require the [GitHub integration](/docs/integrations/github.md) (GitHub App). If no repositories appear, go to **Account Settings** > **Integrations** > **GitHub** to connect your organization.
{% endhint %}
{% endstep %}

{% step %}
**Name the environment**

Enter a descriptive slug (for example, `dev-quickstart`).
{% endstep %}

{% step %}
**Define a blueprint**

Bluebricks creates a blueprint from your source code as part of this flow. Give it a name and optional description. Other team members can reuse this blueprint to deploy the same infrastructure into other collections.
{% endstep %}

{% step %}
**Create the environment**

Click **Create**. Bluebricks generates the blueprint, creates the environment, and triggers the first run automatically.
{% endstep %}
{% endstepper %}

For a deeper walkthrough, see [Creating Environments > From code](/docs/orchestration/environments/creating-environments.md#how-to-create-from-code). To learn how auto-trigger and PR plans work, see [GitOps Environments](/docs/orchestration/environments/gitops-environments.md).
{% endtab %}

{% tab title="GitLab, Azure DevOps & other VCS" %}
If your code lives in GitLab, Azure DevOps, Bitbucket, or another provider, the flow has an extra step. You create a blueprint first, then deploy it into an environment. You can automate future runs by integrating Bluebricks into your CI/CD pipeline.

{% stepper %}
{% step %}
**Create a blueprint and add your code**

1. Go to the [**Packages**](https://app.bluebricks.co/packages) page and click **Create Blueprint**
2. Enter a descriptive name (for example, `application-service`)

Then add your IaC code as an artifact:

There are two ways to create an artifact depending on where your code is stored.

If you’ve connected [GitHub](/docs/integrations/github.md) (or are using a public repo), you can create artifacts directly in the Bluebricks app. If you’re working from a private Github repo or an alternative VCS, artifacts should be published using the CLI.

Choose how you want to create and publish your artifact:

<details>

<summary>Create an artifact directly from the Bluebricks app</summary>

Use this option if you’ve enabled the GitHub integration or are using a public GitHub repository and want your repo to serve as the artifact’s source of truth. Changes to the code will automatically trigger an update process.

To add a artifact:

1. In the packages field, click **+ Add** then click **Create artifact**
2. In the dialog, click **Use repository source**
3. Choose the **repository** and **directory** that contains your IaC code (for example, a Terraform root module)
4. Fill in the artifact details: name, description, and IaC type
5. Click **Create artifact**

</details>

<details>

<summary>Create an artifact with the bricks CLI</summary>

Use this option if your code is in a private repository without the GitHub integration or hosted in another VCS. Artifact updates must be published via your CI pipeline or manually using the CLI.

To add the package:

1. **Open your code’s root directory**\
   Use the folder you’d normally run directly (e.g. `terraform init/apply` or `helm install`).
2. **Publish with the CLI**\
   Run from that directory:

   ```bash
   bricks blueprint publish
   ```

   This generates `bricks.json` and publishes the artifact to the Bluebricks catalog.
3. **Verify in Bluebricks**\
   Go to the [Artifacts](https://app.bluebricks.co/packages?tab=artifact) page in the Bluebricks app to view your newly published artifact and continue to the next step.

</details>
{% endstep %}

{% step %}
**Configure inputs**

Review the inputs that your artifact exposes. For each one, decide whether it should be:

* **Required**: the deployer must provide a value at run time
* **Default**: pre-filled but overridable by the deployer
* **Allowed Values**: a list of permitted values the deployer must choose from

When you are happy with the configuration, save and publish the blueprint. For a deeper walkthrough, see [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md).
{% endstep %}

{% step %}
**Create an environment**

1. Go to the [**Environments**](https://app.bluebricks.co/environments) page and click **Create environment**
2. Choose **From blueprint**
3. Select the collection you created in step 1
4. Name the environment (for example, `dev-quickstart`)
5. Select the blueprint you just published
6. Click **Create** to trigger the first run
   {% endstep %}
   {% endstepper %}

To automate runs from your CI/CD pipeline, see [GitLab CI/CD](/docs/integrations/gitlab.md) or [Azure DevOps](/docs/integrations/azure-devops.md).
{% endtab %}
{% endtabs %}

## 3. Review the plan

After creating the environment, Bluebricks generates a **unified plan** showing every proposed change across all packages in the blueprint.

Review the plan, then **approve** to apply the changes and provision your infrastructure.

If you followed the GitHub tab above, your environment is now Git-connected. Future pull requests targeting the trigger branch automatically generate a plan. Bluebricks posts the results as a GitHub Check Run so reviewers can evaluate infrastructure impact without leaving the PR. See [GitOps Environments > Plan results on pull requests](/docs/orchestration/environments/gitops-environments.md#plan-results-on-pull-requests) for details.

<details>

<summary>Run failed?</summary>

If your run shows a **Failed** status, the review logs open automatically to help you understand what went wrong.

The logs highlight the exact step or package that caused the failure, making it easier to troubleshoot.

</details>

Once the run completes (it can take a few minutes), your resources are live in the target cloud account.

{% hint style="info" %}
**Need additional help?**

Check out our [**Help Center**](https://bluebricks.co/docs/help/) for guides, FAQs, and support resources.
{% endhint %}

## What's next?

Now that you have a running environment, explore these areas to get more out of Bluebricks:

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><p><strong>Properties</strong></p><p>Configure default properties</p></td><td><a href="/files/lHH1zDm65sUzrc052C79">/files/lHH1zDm65sUzrc052C79</a></td><td><a href="/pages/AgwX48yi9NZqdM9IIYyY">/pages/AgwX48yi9NZqdM9IIYyY</a></td></tr><tr><td><p><strong>Policies</strong></p><p>Add approval flows and cost controls</p></td><td><a href="/files/jeSalpFRNhGfcsnCyPwo">/files/jeSalpFRNhGfcsnCyPwo</a></td><td><a href="/pages/JCmPkQRxdAeqDtUKS00A">/pages/JCmPkQRxdAeqDtUKS00A</a></td></tr><tr><td><p><strong>Secrets</strong></p><p>Configure defaults and sensitive values</p></td><td><a href="/files/5ims0xhxke3Uy438Xy9R">/files/5ims0xhxke3Uy438Xy9R</a></td><td><a href="/pages/t8wzCLVozyvEjtnUbg61">/pages/t8wzCLVozyvEjtnUbg61</a></td></tr></tbody></table>

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><p><strong>Bricks CLI</strong></p><p>Manage collections, blueprints, and environments from the command line</p></td><td><a href="/files/5sAVDb84pN0l24HoS0ec">/files/5sAVDb84pN0l24HoS0ec</a></td><td><a href="/pages/dntQmowfGi50XVJh7dBJ">/pages/dntQmowfGi50XVJh7dBJ</a></td></tr><tr><td><p><strong>Drift detection</strong></p><p>Automatically detect when infrastructure drifts from the desired state</p></td><td><a href="/files/EJPLhT7sme2o48rhpql1">/files/EJPLhT7sme2o48rhpql1</a></td><td><a href="/pages/ktcChbC2kbe4xqRWGz2H">/pages/ktcChbC2kbe4xqRWGz2H</a></td></tr><tr><td><p><strong>MCP</strong></p><p>Let AI agents interact with Bluebricks through the Model Context Protocol</p></td><td><a href="/files/B5g045FfRNXDmBjyJrb8">/files/B5g045FfRNXDmBjyJrb8</a></td><td><a href="/pages/lCqJ2UXQQOfXqaFbS3hf">/pages/lCqJ2UXQQOfXqaFbS3hf</a></td></tr></tbody></table>