Orchestration Quick Start

Create your first collection, blueprint, and environment using the Bluebricks orchestration platform.

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.

New to Bluebricks? Start with the Quick Start to connect your cloud and meet the agent. This guide is for teams setting up orchestration workflows.

Before you start

Read the Orchestration Overview 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)
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 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:

Create a collection

Go to the Collections page in the Bluebricks app
Click Create collection
Enter a name (for example, dev-quickstart)

Connect your cloud provider

Continuing from the create collection dialog:

Select your cloud provider: AWS, GCP, Azure, or Self-hosted
In Account Number / ID dropdown, click Create new
Follow the setup steps to grant Bluebricks the necessary permissions
1. For provider-specific instructions, see Connect your Cloud
Click Connect & Create

2. Create an environment

An environment connects a blueprint to a collection and tracks the full lifecycle of your infrastructure: planning, applying, and tearing down resources.

From the Environments page, click Create environment to get started.

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

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.

Select a collection

Choose the collection you created in step 1.

Set source code

Select your IaC technology (OpenTofu, Terraform, Helm, CloudFormation, or Bicep)
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)
Set the branch and, optionally, a subdirectory path

Private repositories require the GitHub integration (GitHub App). If no repositories appear, go to Account Settings > Integrations > GitHub to connect your organization.

Name the environment

Enter a descriptive slug (for example, dev-quickstart).

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.

Create the environment

Click Create. Bluebricks generates the blueprint, creates the environment, and triggers the first run automatically.

For a deeper walkthrough, see Creating Environments > From code. To learn how auto-trigger and PR plans work, see GitOps Environments.

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.

Create a blueprint and add your code

Go to the Packages page and click Create Blueprint
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 (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:

Create an artifact directly from the Bluebricks app

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:

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

Create an artifact with the bricks CLI

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:

Open your code’s root directory Use the folder you’d normally run directly (e.g. terraform init/apply or helm install).
Publish with the CLI Run from that directory:
```
bricks blueprint publish
```
This generates bricks.json and publishes the artifact to the Bluebricks catalog.
Verify in Bluebricks Go to the Artifacts page in the Bluebricks app to view your newly published artifact and continue to the next 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.

Create an environment

Go to the Environments page and click Create environment
Choose From blueprint
Select the collection you created in step 1
Name the environment (for example, dev-quickstart)
Select the blueprint you just published
Click Create to trigger the first run

To automate runs from your CI/CD pipeline, see GitLab CI/CD or Azure DevOps.

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 for details.

Run failed?

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.

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

Need additional help?

Check out our Help Center for guides, FAQs, and support resources.