Runs

Plan and apply infrastructure changes through runs

A run is a single execution of an environment. Each time you deploy, update, or destroy infrastructure through Bluebricks, you trigger a run. Runs are divided into two phases, plan and apply, with an optional approval step in between.

Every run is fully tracked: Bluebricks records the plan output, apply logs, inputs, outputs, and state changes. This gives your team a complete, auditable history of how your infrastructure has changed over time.

How runs work

Every run executes against a published, immutable version of the blueprint, not the latest code in your repository. This guarantees that what you reviewed in the plan phase is exactly what gets applied.

When a run starts, Bluebricks evaluates the blueprint and all its child packages to build a directed acyclic graph (DAG). This determines the order in which packages are planned and applied: parallel where possible, sequential where dependencies require it.

Plan phase

During the plan phase, Bluebricks iterates through each package in the DAG and produces a unified plan. The plan captures every expected change across all layers of infrastructure, including resources to be created, updated, or destroyed, before anything is applied.

Once planning is complete, the run pauses and surfaces the plan for review. You can inspect the full diff before deciding whether to proceed.

Approval

After the plan phase, you can approve or reject the run. If your collection has an owner approval policy configured, a designated collection owner must approve before the run can proceed.

You can also configure environments to auto-approve, skipping the review step and proceeding directly to apply.

Apply phase

When the run is approved, Bluebricks executes the plan in the same order it was evaluated. During each step, it collects outputs from the completed package and passes them to the next package in the sequence.

Once the apply phase is complete, Bluebricks updates the environment state and records the run in the environment's history.

How to trigger a run

You can trigger a run from any of the following interfaces:

• Web app: initiate a run manually from the environment page

• MCP: trigger runs through Model Context Protocol for AI agent integrations

• Bricks CLI: use the bricks install command to trigger a run from your terminal

• API: trigger runs programmatically via the Deployments API

• Webhooks: configure webhooks to trigger runs automatically on external events

• CI/CD pipelines: integrate with GitHub Actions, GitLab, Azure DevOps, and other CI/CD tools

Regardless of how a run is triggered, every execution follows the same plan-approve-apply lifecycle and is fully recorded in the environment's history.