---
title: "Environments"
description: "Register an environment for a branch and a project, the bots and policies the console creates for it, and pausing it."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

An environment deploys one branch of the stack's repository into one project. It's registered
once in the console, under the stack's **Settings**, with **Register environment**: its name (as
the file's `environments` names it), its branch, its project, and whether plans need approval.

## One environment per project

A project holds at most one Deploy environment, and registering a second one there is refused.
Use a project for this environment only: its resources are created there. Deploy doesn't create
projects.

## What the console creates

Registering runs in your browser, as you, so you need the IAM permissions for each step; the
console names any you're missing. For a stack `shop` and an environment `production`, it creates:

| Created | Name | What it's for |
| --- | --- | --- |
| A policy | `ezgh-deploy-shop-production` | What the deploy bot may do: the write actions Deploy uses, on the environment's project |
| A policy | `ezgh-deploy-shop-production-services` | The deploy bot's boundary for the bots it creates for services |
| A policy | `ezgh-deploy-shop-production-images` | Pushing images to the stack's `ci.registry` scope in Container Registry |
| The deploy bot | `deploy-shop-production` | Makes every change in the environment |
| The image bot | `deploy-shop-production-images` | Pushes the environment's built images |

It then adds the trust entries:

- the deploy bot trusts `deploy.ezghcloud.com` for this repository on `refs/heads/<branch>` only;
- the image bot trusts `build.ezghcloud.com` for this repository on `refs/caller/<branch>`, the builds
  Deploy asks EZGH Build for;
- the stack's Build connection bot trusts `build.ezghcloud.com` for this repository on
  `refs/caller/**`.

Last, it registers the environment with Deploy, which reads both bots back and refuses the
registration unless each holds exactly what was generated for it. If a step fails, submitting
again resumes where it stopped.

## Keep the bots as they were made

Deploy checks both bots again at the start of every deployment. A deployment fails, naming what
changed, if either bot holds anything else: another policy, a group, another trust entry, or an
API key. Don't add a break-glass API key to the deploy bot; make a separate bot for that.

Changing `ci.registry` changes the images policy, so the deployment fails with a message naming
the image bot to update.

## Why another branch can't deploy it

The deploy bot trusts Deploy only for the environment's own branch, and each environment reads
`EZGHDeploy` from that branch. A file whose `environments.<name>` names a different `branch` or
`project` than the registration is refused before anything is planned, so a push to `develop` can
never deploy `production`. An environment in the file that isn't registered deploys nothing.

## Pause

**Pause** on the environment stops new deployments: pushes start none, and deployments already
running stop at the end of their current step, as `cancelled`. Running services keep running.
**Resume** lets the next push deploy again.

## Delete an environment

Deleting an environment tears down its services and detaches every resource. Nothing else is
deleted: databases, caches, queues, buckets and secrets stay in the project. The console asks you
to type the environment's name. A stack can be deleted once all its environments are.

| Action | Permission |
| --- | --- |
| Register | `deploy.environments.create` |
| Pause | `deploy.environments.pause` |
| Resume | `deploy.environments.resume` |
| Delete | `deploy.environments.delete` |

Source: https://docs.ezghcloud.com/deploy/environments/index.mdx
