---
title: "Connect your environment repo"
description: "GitOps with the Frazer Reader app."
url: https://frazer.ai/docs/quickstarts/environment-repo
index: https://frazer.ai/docs/llms.txt
tokens: 1808
---

> For agents: this page is indexed at https://frazer.ai/docs/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Connect your environment repo

At the end of this guide, the cluster `acme-staging-1` deploys what is in the folder `envs/staging` of your GitHub repository `acme/platform-envs`. Frazer reads the repository through the read-only **Frazer Reader** GitHub App, and the cluster’s own Frazer GitOps applies every commit. This connection is an **environment**: a repository, a revision, a path and the namespaces it owns.

You need:

-   A cluster. [Create a Kubernetes cluster](https://frazer.ai/docs/quickstarts/kubernetes-cluster) first if you have none.
-   A GitHub repository for deployment configuration, kept apart from your code repositories, and the right to install a GitHub App on it. This guide uses `acme/platform-envs`.
-   A role in the project that may connect environments with the `standard` profile; Developers may.
-   `kubectl` with credentials for the cluster: run `frazer kubernetes clusters get-credentials acme-staging-1 --project acme-staging`.

## Connect the repository

1.  **Install the CLI and sign in.**
    
    ```sh
    curl -fsSL https://get.frazer.ai | sh
    frazer login
    ```
    
2.  **Lay out the repository.** Keep one folder per environment on one branch; promotion is a pull request that copies a change from `envs/staging` to `envs/production`. Frazer reads this layout:
    
    ```text title="acme/platform-envs"
    envs/staging/                       # the connected path
    ├── environment.yaml                # optional: labels, namespace defaults
    ├── _shared-values.yaml             # environment-wide Helm values
    ├── apps/<family>/<app>/
    │   ├── values.yaml                 # written by people
    │   └── images.yaml                 # written by CI only: the image digest
    ├── databases/<name>/database.yaml  # Postgres, with backups
    └── manifests/<name>/               # raw YAML or a Kustomization
    ```
    
    To check delivery end to end, commit one small manifest and push it to `main`:
    
    ```yaml title="envs/staging/manifests/hello/configmap.yaml"
    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: hello
      namespace: web
    data:
      message: Delivered from acme/platform-envs
    ```
    
3.  **Install the Frazer Reader app.** In the console, open the cluster (**Compute › Kubernetes clusters › acme-staging-1**), then **Environments › Connect**. Pick the repository from the Frazer Reader installation; the first time, install the app on GitHub and select `acme/platform-envs`, and later extend the installation to add repositories. The app reads contents and metadata, nothing more. Each cluster gets a 60-minute read token, refreshed every 20 minutes and limited to the repositories connected to it.
    
4.  **Plan the environment.** Name it `platform`, give it the path and the namespaces it owns, and keep the `standard` profile:
    
    ```sh
    frazer releases environments connect platform --project acme-staging --cluster acme-staging-1 \
      --repo acme/platform-envs --path envs/staging \
      --namespaces checkout-api,web --profile standard --dry-run
    ```
    
    In the console, the **Connect** form asks for the same: the branch (`main`), the path, the namespaces and the profile, with the sync policy and hostnames, which you can leave at their defaults. The plan appears beside it.
    
    The plan is computed from the repository’s current contents:
    
    ```text title="Output"
    Plan: connect environment "platform" to cluster acme-staging-1 (acme-staging)
      + Namespaces      env-platform, checkout-api, web
      + AppProject      env-platform   source acme/platform-envs + Frazer Registry · profile standard
      + Applications    1 from commit 3f9c2e1: hello
      ~ Git token       cluster acme-staging-1 also reads acme/platform-envs
      ✓ Namespaces      no conflict
      ✓ Policy          Policy dry run: 0 violations · schemas valid
    ```
    
    The AppProject `env-platform` fences the environment: only this repository and Frazer Registry as sources, only its own namespaces, and under `standard` no cluster-scoped kinds, Gateways, or network-plugin, gateway-controller and GitOps kinds. If another environment already owns one of the namespaces, the plan fails.
    
5.  **Apply it.** Run the command again without `--dry-run`, or click **Apply** in the console. An environment with the `platform` profile, which may add CRDs and operator webhooks, waits for an organization admin’s approval; `standard` does not.
    
6.  **Check that it synced.**
    
    ```sh
    kubectl get configmap hello -n web
    ```
    
    **Open GitOps** on the cluster’s page shows the Application `hello` in the project `env-platform`, synced and healthy. From now on, every push to `envs/staging` syncs: automatically, with prune and self-heal. Namespaces, volume claims, CRDs and databases are never deleted without a confirm. To roll back, revert the commit.
    

> **Caution:** Never commit a `Secret` with data. Commit `ExternalSecret` objects; the values live in Frazer Secrets, and an admission policy rejects a `Secret` that carries `data` or `stringData`.

## Deploy your services

-   **Apps** are folders under `apps/<family>/<app>/`. A family is a chart: Frazer ships a general `app` chart, and you can push your own chart families to Frazer Registry. Values layer from the chart’s defaults through `_shared-values.yaml` and the app’s `values.yaml` to `images.yaml`.
-   **Images** come from your CI: it builds once, pushes to Frazer Registry (which signs the digest on push) and writes the digest into the app’s `images.yaml`, in staging by commit and in production by pull request. Admission checks the signature.
-   **Pull-request checks.** Install the **Frazer Reviewer** app and every pull request that touches a connected path gets a check run per environment, such as `Frazer / acme-staging / platform`: the rendered diff from the cluster’s own Frazer GitOps, policy results, signature checks and the change in requests and cost. Make it required in your branch rules.
-   **Pull requests from Frazer**, such as promotions and restores, go through the separate **Frazer** app, which you install only if you want Frazer to write to the repository.

## Next steps

[Environments and GitOps](https://frazer.ai/docs/gitops) Layouts, modes, permission profiles, promotion and sync defaults.

[Kubernetes](https://frazer.ai/docs/kubernetes) The clusters your environments deploy to.

[Registry](https://frazer.ai/docs/registry) Push signed images from CI without stored keys.

[Secrets](https://frazer.ai/docs/secrets) Keep values out of Git with ExternalSecret objects.

## Pages in Get started

- [Docs home](https://frazer.ai/docs.md)
- [Bring your first server](https://frazer.ai/docs/quickstarts/first-server.md)
- [Create a Kubernetes cluster](https://frazer.ai/docs/quickstarts/kubernetes-cluster.md)
- [Deploy serverless with Postgres](https://frazer.ai/docs/quickstarts/serverless-postgres.md)
- [Deploy an open model](https://frazer.ai/docs/quickstarts/open-model.md)
- [Give your team devboxes](https://frazer.ai/docs/quickstarts/devboxes.md)
- [Connect your environment repo](https://frazer.ai/docs/quickstarts/environment-repo.md) (this page)