Skip to content

Deployments

How a deployment moves from a push to a rollout, its plan and the changes it refuses, approval, cancelling and rolling back.

Updated View as Markdown

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);
  • 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
Navigation

Type to search…

↑↓ navigate↵ selectEsc close