# 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. {% hint style="success" %} **Try it with the agent.** The agent handles plan/approve/apply flows through conversation. See [Agent Overview](/docs/agent/agents-overview.md). {% endhint %} 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. For details on how the DAG works and how to optimize for parallelism, see [Parallel Execution](/docs/orchestration/runs/parallel-execution.md). ### 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. The plan output groups changes into four categories: resources to create, resources to update, resources to destroy, and resources with no changes. This unified view spans every package in the blueprint so you can review all proposed changes in one place. Once planning is complete, the run pauses and surfaces the plan for review. You can inspect the full diff before deciding whether to proceed. {% @mermaid/diagram content="sequenceDiagram participant C as Client participant B as Bluebricks participant O as Orchestrator ``` C->>B: Trigger run B->>B: Create run task O-->>B: Poll for pending tasks O->>O: Build DAG & plan packages O->>B: Plan complete B->>C: Plan ready for review" %} ``` ### Approval After the plan phase, you can approve or reject the run. If your collection has an [owner approval](/docs/orchestration/collections/owners-and-members.md) 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. {% @mermaid/diagram content="sequenceDiagram participant C as Client participant B as Bluebricks participant O as Orchestrator ``` C->>B: Approve run B->>B: Update run stage O-->>B: Poll for pending tasks O->>O: Apply packages in DAG order O->>B: Run complete B->>C: Run complete" %} ``` ## Git source Runs triggered from a git-connected environment display their source context in the **Git source** column on the **Runs** tab.
The Runs tab showing the Git source column with PR number, branch, and commit SHA for each run
Each git-triggered run shows: * **PR number**: links to the pull request that triggered the run * **Branch name**: the head branch of the pull request or push event * **Commit SHA**: the short commit hash, links to the commit in your VCS provider. Hover to see the commit author Runs not triggered by a git event display "n/a" in the Git source column. ## 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](/docs/orchestration/environments/creating-environments.md) * **Git push:** connect an environment to a repository so that pushes or pull requests trigger runs automatically * **MCP:** trigger runs through [Model Context Protocol](/docs/integrations/bricks-mcp.md) for AI agent integrations * **Bricks CLI:** use the [`bricks install`](/docs/bricks-cli/cli-reference/bricks_install.md) command to trigger a run from your terminal * **API:** trigger runs programmatically via the [Deployments API](https://bluebricks.co/docs/api/reference/deployments) * **Webhooks:** configure webhooks to trigger runs automatically on external events * **CI/CD pipelines:** integrate with [GitHub Actions](/docs/integrations/githubactions.md), [GitLab](/docs/integrations/gitlab.md), [Azure DevOps](/docs/integrations/azure-devops.md), 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. --- # 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.md?ask= ``` 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.