> For the complete documentation index, see [llms.txt](https://bluebricks.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bluebricks.co/docs/orchestration/environments/gitops-environments.md).

# 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