# 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>


---

# 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/orchestration-quick-start.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.