# GitOps Environments

## Overview

The basic promise of infrastructure as code is simple: when you change your code, your infrastructure should respond. Bluebricks lets you connect an environment directly to\
a Git repository so that every push triggers a run and every pull request gets a plan.

No CI/CD pipeline to build or maintain, and no need to manually create or version artifacts or blueprints; Bluebricks handles all of that from your source code.

<figure><picture><source srcset="/files/idqTampbHlXTUuTHABC7" media="(prefers-color-scheme: dark)"><img src="/files/YI5XIx0A2or1PK0fj7Ut" alt=""></picture><figcaption></figcaption></figure>

### How it works

When you create an automated environment, Bluebricks registers a webhook on your GitHub repository through the GitHub App. From that point, the flow is automatic: you push code (or open a PR), Bluebricks publishes an updated blueprint from the source, triggers a run, and posts the plan results back to the PR as a [check run](#plan-results-on-pull-requests).

* **Push to the trigger branch**: Bluebricks runs a full plan and apply
* **Pull request targeting the trigger branch**: Bluebricks runs a **plan only** (changes are never applied from a PR)

{% hint style="info" %}
The auto-trigger pipeline is read-only: it clones your repository and publishes a blueprint to the Bluebricks registry, but never pushes files back. Files generated during publishing (such as `bricks.json`) must be committed to your repo manually if you need them in version control.
{% endhint %}

<figure><picture><source srcset="/files/4gXzJnKWIwAOswsoxP2F" media="(prefers-color-scheme: dark)"><img src="/files/LqpqcHTUzkZnJmvjRlfA" alt=""></picture><figcaption></figcaption></figure>

### Auto-trigger rules

Every automated environment has a **trigger branch**, the branch you select when creating the environment (e.g., `main`). Auto-trigger behavior depends on the type of Git event.

<details open>

<summary>Push events</summary>

When code is pushed to the trigger branch, Bluebricks triggers a full **install** run (plan followed by apply). This is the default behavior for automated environments.

Pushes to other branches are ignored. Only the configured trigger branch activates the pipeline.

</details>

<details>

<summary>Pull request events</summary>

When a pull request is **opened**, **updated** (new commits pushed), or **reopened** against the trigger branch, Bluebricks triggers a **plan-only** run. This is a safety guard: pull request events never trigger an apply, regardless of configuration.

The plan output is posted back to the PR as a GitHub Check Run so reviewers can evaluate the infrastructure impact before approving the merge.

When a pull request is **closed** (merged or abandoned), Bluebricks cancels any pending check runs associated with that PR.

</details>

<details>

<summary>Blueprint publish events</summary>

If a new version of the linked blueprint is published through other means (e.g., the CLI or API), Bluebricks also triggers an auto-run on any environment with auto-trigger enabled for that blueprint. This ensures environments stay in sync even when blueprints are updated outside the Git flow.

</details>

### Plan results on pull requests

When a pull request targets the trigger branch of an automated environment, Bluebricks creates a **GitHub Check Run** named `Bluebricks Run: <environment-slug>`. The check run progresses through several states:

<table><thead><tr><th width="219.23828125">Check Run status</th><th>Meaning</th></tr></thead><tbody><tr><td><strong>Queued</strong></td><td>The environment is waiting for a previous run to finish</td></tr><tr><td><strong>In progress</strong></td><td>Bluebricks is analyzing the repository or executing the plan</td></tr><tr><td><strong>Completed (success)</strong></td><td>The plan succeeded. The check run output contains the full plan details</td></tr><tr><td><strong>Completed (failure)</strong></td><td>The plan failed. The check run output contains error details</td></tr><tr><td><strong>Cancelled</strong></td><td>The PR was closed or the run was superseded by a newer push</td></tr></tbody></table>

The plan output (resource changes, additions, and deletions) appears directly in the check run's **output tab** on GitHub. Reviewers can read the infrastructure plan without leaving the pull request.

{% hint style="info" %}
If an environment already has a running deployment when a new PR event arrives, the new run is **queued** and starts automatically once the current run completes.
{% endhint %}

### How to set up an automated environment

To create an automated environment, use the **From code** flow in the **Create environment** modal. For step-by-step instructions, see [Creating Environments > Connect source](/docs/orchestration/environments/creating-environments.md#connect-source).

Bluebricks generates a blueprint from your source code, creates the environment, and triggers the first run. You must **approve and apply this initial run** to activate auto-trigger. Once the first run completes, the webhook is registered and every subsequent push to the configured branch and every PR targeting it automatically triggers runs.

{% hint style="warning" %}
Auto-trigger requires the [GitHub integration](/docs/integrations/github.md) (GitHub App). Public repositories created without the GitHub App do not support auto-trigger or check runs.
{% endhint %}

### Limitations

* **Single trigger branch**: each environment is linked to one branch. Pushes to other branches do not trigger runs
* **Cannot link existing environments**: you can only create a *new* automated environment through the "From code" flow. Connecting an existing environment to a Git repository via the UI is planned for a future release


---

# 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/gitops-environments.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.