# 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="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FSOLz6QYUetw7ewjXSXde%2Frun%20git%20dark.png?alt=media&#x26;token=1db85d66-c23c-449e-a0d4-a218cffbe2cc" media="(prefers-color-scheme: dark)"><img src="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FFaT9aRZEfJ9qaO2wqKE4%2Frun%20git%20light.png?alt=media&#x26;token=8351474e-e621-44c9-a6bb-34b6dd8083f4" 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)

<figure><picture><source srcset="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2FK0gwwKJn3V674rSPVKEU%2Fall%20checks%20TACO%20dark.png?alt=media&#x26;token=fc36bbe0-f9f5-4f85-9237-8ed5411f7078" media="(prefers-color-scheme: dark)"><img src="https://454695563-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FL1aVoJ67VgVl8Uv83TuE%2Fuploads%2Fj73YbObwX1QESMMadJFo%2Fall%20checks%20TACO%20light.png?alt=media&#x26;token=84b96eb1-1700-4dae-8fc2-0c105920c552" 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](https://bluebricks.co/docs/core-concepts/creating-environments#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](https://bluebricks.co/docs/integrations/github) (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