# Environments A Bluebricks **environment** provides a consistent, controlled, and repeatable way to execute a [blueprint](/docs/orchestration/packages/blueprints-overview.md) against a specific [collection](/docs/orchestration/collections.md). An environment represents the ongoing workflow responsible for provisioning, updating, and destroying all infrastructure defined by the blueprint, across every package, artifact, and dependency it contains. {% hint style="success" %} **Try it with the agent.** Deploy, update, and govern environments through conversation with built-in approval flows. See [Agent Overview](/docs/agent/agents-overview.md). {% endhint %} Once created, an environment serves as the stable interface for managing the lifecycle of your infrastructure in that collection. It centralizes configuration, tracks every change, and ensures that updates are performed safely and predictably, whether triggered manually, through CI/CD, or [automatically from Git](/docs/orchestration/environments/gitops-environments.md).
## How environments work When you create an environment [run](/docs/orchestration/runs.md), Bluebricks evaluates the blueprint and all of its child [packages](/docs/orchestration/packages.md) to produce a **unified execution plan**. This plan captures every expected change across all layers of infrastructure, allowing you to: * Preview changes before applying them * Understand the full impact of updates * Maintain an auditable history of every modification Each execution of an environment creates a [**run**](/docs/orchestration/runs.md), which encapsulates the plan, logs, state updates, and resulting outputs. Runs are fully versioned and traceable, enabling teams to understand how infrastructure evolves over time and why each change was made. ## What an environment contains An environment bundles configuration, execution history, and lifecycle controls into a single manageable unit: * **Blueprint binding**: the specific blueprint (and version) that defines the infrastructure to provision * **Collection target**: the collection that determines where resources are created and which policies, variables, and secrets apply * **Run history**: a full audit trail of every plan, apply, and destroy run, including logs, diffs, inputs, and outputs * **Lifecycle controls**: [drift detection](/docs/orchestration/environments/drift-detection.md) schedules, [TTL](/docs/orchestration/environments/environment-ttl.md) rules, and [archiving](/docs/orchestration/environments/archiving-environments.md) state that govern how the environment behaves over time ## GitOps environments You can connect an environment directly to a Git repository so that every push triggers a run and every pull request gets a plan. Bluebricks registers a webhook through the GitHub App and handles the full cycle: publishing an updated blueprint from source, triggering the run, and posting the plan back to the PR as a GitHub Check Run. For setup instructions, auto-trigger rules, and limitations, see [GitOps Environments](/docs/orchestration/environments/gitops-environments.md). ## The environment detail page When you review an environment, the detail page organizes everything into four tabs: **Overview**, **Drift detection**, **States**, and **Environment TTL**.
### Overview tab The Overview tab is the default view. It shows general information about the environment and a complete run history.
General info displays at the top of the page * **Collection**: the target collection with its cloud provider badge * **Blueprint**: the installed blueprint name, version, and a badge if a newer version is available * **Status**: the current environment status with a drift indicator * **Current cost**: the estimated cost of provisioned resources (or "n/a" if unavailable)
Run history lists every run for the environment in a table You can filter by type, stage, or who initiated the run. Each row shows: * **Blueprint and version**: which blueprint version the run used * **Type**: Install, Uninstall, Plan only, or Drift detection * **Cost change**: the cost before and after the run * **Actions**: a summary of planned and actual resource changes * **Stage**: the current run stage with a timestamp * **Participants**: avatars for the creator and reviewer * **Git source**: the linked PR, branch, or commit (if triggered from Git) From each row, you can review the plan, trigger a new run, [promote](/docs/orchestration/runs/promoting-environments.md) to another collection, or delete the run.
### Drift detection tab The Drift detection tab lets you enable automatic drift detection and view drift history. When enabled, Bluebricks runs a daily plan-only check at 00:00 UTC to compare your deployed infrastructure against the blueprint definition. You can also enable auto-remediation to automatically correct any detected drift. For setup instructions and details on how drift detection works, see [Drift Detection](/docs/orchestration/environments/drift-detection.md). ### States tab The States tab lists all infrastructure state files managed within the environment. For each state, you can see the associated package, version, and who last updated it. Actions include downloading, viewing (with version history), or uploading a state file. For details on state ownership models, see [State Management and History](/docs/orchestration/runs/state-management-and-history.md). ### Environment TTL tab The Environment TTL tab lets you schedule automatic uninstalls on a daily or weekly cadence. This is useful for ephemeral environments (dev, staging, sandboxes) where you want to avoid accumulating unused infrastructure. For setup instructions and scheduling options, see [Time to Live (TTL)](/docs/orchestration/environments/environment-ttl.md). ## Best practices * **Use descriptive slugs** (e.g., `networking_prod`, `data_staging`) so environments are easy to identify in lists and automation * **Review the unified plan before approving** to understand the full impact of changes across all packages * **Enable drift detection** on long-lived environments to catch out-of-band changes early * **Set a TTL on ephemeral environments** (e.g., feature branches, demos) to avoid unused infrastructure accumulating cost * **Archive environments you no longer need** instead of leaving them in the active list. See [Archiving Environments](/docs/orchestration/environments/archiving-environments.md) --- # 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/environments.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.