---
title: "Deployments"
description: "How a deployment moves from a push to a rollout, its plan and the changes it refuses, approval, cancelling and rolling back."
---

> 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.

# Deployments

A deployment (`dpl_…`) starts on a push to an environment's branch, on a canvas commit landing
there, or with `ezgh deploy apply`. One deployment at a time changes an environment. A newer
deployment cancels an older one that hasn't started applying (as `superseded`); one that is
applying finishes first, and the newer one waits.

## Statuses

| Status | The deployment |
| --- | --- |
| `queued` | Waits for the environment's previous deployment |
| `validating` | Reads `EZGHDeploy` at the commit and checks it, its registration and the referenced secret fields |
| `building` | Waits for the `ci.requires` tasks of the push's Build pipeline, and builds each service's image |
| `planning` | Compares the file with the live resources and makes a plan |
| `awaitingApproval` | Waits for a person to approve the plan |
| `applying` | Creates and changes resources |
| `awaitingDns` | Waits for DNS records you add (see below) |
| `releasing` | Runs the `release.command` |
| `rollingOut` | Rolls out each changed service |
| `cancelling` | Finishes its current step, then stops |
| `succeeded`, `failed`, `cancelled` | Is finished |

A failed step stops the deployment. What it already applied stays, and the next deployment starts
from the live state. A failed rollout puts the service's traffic back on the previous version.
Each deployment reports a check on its commit, linked to the deployment in the console.

| Waiting in | At most | Then |
| --- | --- | --- |
| `building` | 60 minutes | `failed` |
| `awaitingApproval` | 7 days | `cancelled` |
| `awaitingDns` | 72 hours | `failed` |

## Plans

A plan lists every change, grouped by action: create, change (each field as `from → to`),
replace, detach, and each service rollout. The file wins for every field it sets, so a value
changed on a product's own page shows as a change back. Fields the file doesn't set are never
touched.

Some changes are **refused**, each with its reason, and nothing in the plan is applied:

- an impossible change, such as shrinking storage or changing a value fixed at creation;
- a key that names a resource already in the project that the environment doesn't manage
  (attach it first, see [Managed resources](/deploy/resources));
- any change to a managed data resource that is `missing`.

Renaming a resource's key shows as "detach the old key, create the new one", and always needs
approval.

## Approval

With `approve: true` on the environment (or when the plan renames a key), a deployment waits in
`awaitingApproval`. **Approve** applies exactly the plan you read; **Reject** cancels it.

Approving needs `deploy.deployments.approve` **and** every action the plan uses, on the
environment's project: approval can't grant more than you already hold. When you're missing one,
the console names each. Reading a plan needs `deploy.files.read`, since it shows the file's
values. If the live resources change after the plan was made, approving makes a new plan to
approve.

In the CLI, `ezgh deploy approve <deployment>` shows the plan and asks before approving it.
`--plan-hash` approves exactly the plan with that hash, from `ezgh deploy plan --json`, without
asking.

## Waiting for DNS

When a public domain's zone is in EZGH DNS, Deploy writes its records and the certificate
validates by itself. Otherwise the deployment waits in `awaitingDns` and shows the records to add
at your DNS provider. It continues once the certificate validates.

## Cancel

**Cancel** stops a deployment at the end of its current step. A rollout in progress returns
traffic to the previous version. Resources already changed stay changed.

## Roll back

**Roll back** (or `ezgh deploy rollback --to <deployment>`) deploys an earlier succeeded deployment
again: its commit and its images. Rollback covers services only; resources keep their current
settings. The canvas then shows that the environment runs that deployment rather than the file at
the branch head, until the next push deploys the head again. Rollback never writes to the branch;
revert the commit yourself to keep it.

| Action | Permission |
| --- | --- |
| List and see deployments | `deploy.deployments.list`, `deploy.deployments.get` |
| Read a plan | `deploy.files.read` |
| Deploy the branch now | `deploy.deployments.create` |
| Approve or reject | `deploy.deployments.approve`, and every action in the plan |
| Cancel | `deploy.deployments.cancel` |
| Roll back | `deploy.deployments.rollback` |

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