Skip to content

The EZGHDeploy file

Services, resources, secrets and environments in EZGHDeploy, how references wire them together, and the file's limits.

Updated View as Markdown

EZGHDeploy sits at the root of the repository. Each environment reads it from its own branch. Every key is listed in the file reference. Check a file before you push it with ezgh deploy validate, which prints each problem with its place in the file and an example that would be accepted. ezgh deploy init writes a first file for a checkout.

Format

The file is plain YAML, read strictly:

  • no anchors, aliases, merge keys, tags or second documents;
  • no duplicate or unknown keys;
  • text that looks like a number or a boolean (1.0, no, "18") must be quoted.
Limit Value
File size 256 KiB
Nesting 8 levels
Items in a list 64
Services 50
Resources 50
Sandbox images 20
Environments 10

Names of services, resources, sandbox images, secrets and environments are a lowercase letter, then up to 39 lowercase letters, digits or hyphens. A name is used once across services, resources and sandbox images.

Top-level keys

Key What it holds
version Always 1
name The stack’s name
region Always us-west-1
runtime Where services run: instances
services The things that run your code
resources Databases, caches, queues and buckets
sandboxImages Images built from the repository for the sandboxes services start
secrets Secrets in EZGH Secrets, with their fields
environments The branches that deploy, and the project each deploys into
ci EZGH Build tasks a deployment waits for, and where images go
alerts Observability alert rules

Runtime

With runtime.mode: instances (the default), each service is an autoscaling group with one container on each instance, in a VPC per environment. Services set instanceType, and a service that sets no size runs one gs-1.large instance.

runtime.image is the instance image containers run on: linux/ubuntu:24.04.

Services

A service’s type is web (it listens on port) or worker (no port).

Each service is built from exactly one of:

Key Builds
source A directory whose language and framework are detected. No Dockerfile needed.
dockerfile Your own Dockerfile: a directory holding it (./services/api/ builds services/api/Dockerfile), or the Dockerfile’s path, such as ./services/api/Dockerfile.prod. The build context is the repository root.
image A prebuilt image, by tag or @sha256 digest.
from Another service’s image, usually with a different command.

Images built from source and dockerfile are pushed to Container Registry under ci.registry, in the project of the stack’s EZGH Build connection. Every deployment runs each image by its digest.

Detection

source directories are detected in this order; the first match wins:

  1. PHP: composer.json or index.php
  2. Go: go.mod
  3. Python: requirements.txt, pyproject.toml, Pipfile, uv.lock or poetry.lock
  4. Node: package.json, with npm, pnpm, Yarn or Bun
  5. A static site: index.html
  6. Anything else, when build.startCommand is set

Otherwise the deployment fails with “add a Dockerfile, or set build.startCommand”.

Language Version read from Supported Default
Node .nvmrc, .node-version, package.json engines.node 22, 24, 26 26
Bun packageManager: bun@<version> 1 1
Python .python-version, runtime.txt, pyproject.toml requires-python, Pipfile 3.11 to 3.15 3.14
Go go.mod toolchain, then go 1.26, 1.27 1.27
PHP composer.json require.php 8.2 to 8.5 8.5

build.installCommand, build.buildCommand and build.startCommand each replace the detected command. The start command runs through /bin/sh -c, so ./migrate && ./serve works. Yarn 2 or later needs packageManager in package.json (such as "yarn@4.5.0"), and SvelteKit needs @sveltejs/adapter-node or @sveltejs/adapter-static. ezgh deploy detect [dir] prints what detection found, and why.

Prebuilt images

image names a repository in Container Registry, in the project of the stack’s Build connection:

  • <scope>/<name>, an image you pushed, such as shop/imgproxy:v3;
  • <prefix>/<namespace>/<name> under an active pull-through cache rule, such as hub/library/nginx:1.27 for Docker Hub’s nginx:1.27.

An image on another registry fails the deployment: push it to Container Registry, or pull it through a cache rule.

Public services

A web service is private unless it has public. public.domains get a load balancer with certificates issued and renewed by Certificates, and optionally a CDN distribution (cdn) and a WAF (waf). A domain behind the CDN can’t be an apex domain such as example.com. When a domain’s zone is in EZGH DNS, Deploy writes its records; otherwise the deployment waits for you to add them (see Deployments).

Rollouts and release commands

rollout.strategy is rolling (the default; batchPercent replaces a share of instances at a time) or canary, for public services, which shifts traffic through rollout.steps (weight in percent, then pause). release.command runs once per deployment before any rollout, such as a database migration; if it fails, nothing rolls out. shutdown.graceSeconds is the time a stopping instance gets to finish its work.

Resources

type Creates
mysql (Percona Server; also percona), mariadb, postgresql A database in Databases
redis (Valkey; also valkey), memcached A cache in Caches
warehouse A warehouse in Warehouse
queue A queue in Queues
bucket A bucket in Object Storage

A resource’s product name is its name, or its key when name is left out. Its type, and a queue’s queueType, are the same in every environment. Bucket names are unique across EZGH Cloud, so a bucket in more than one environment needs its own name in each environment’s overrides. Logical databases and a warehouse’s databases are only ever created: removing one from the file leaves it in place.

References

An env value is text, or exactly one reference as the whole value:

Reference Is
${{ resources.<name>.<attribute> }} An attribute of a resource, such as uri or host
${{ services.<name>.url }} Another web service’s URL
${{ secrets.<name>#<field> }} A field of a secret the file lists
${{ sandboxImages.<name>.image }} A sandbox image, by digest. Needs sandboxes: true on the service

References are allowed only in env. The file reference lists each type’s attributes. A database reference reaches its first logical database, and a warehouse’s database attribute is its first database, or default.

A reference is also the access rule. A service can connect only to the databases, caches, warehouses and services it references, through its own firewall. It gets its own database user on each database it references, with access readOnly, readWrite (the default) or owner, its own cache user, and its own user on each warehouse it references, with the warehouse’s access readOnly, readWrite (the default) or admin. Queues, secrets and buckets are reached as the service’s own bot, whose policy names only what it references.

Sandboxes

sandboxes: true on a service lets its bot create and use EZGH Sandboxes in the environment’s project: every sandbox action, on that project’s sandboxes. It’s false when left out. The bot can run commands and write files only in sandboxes that have no bot; in a sandbox that has one, those also need bots.pass on its bot. Removing sandboxes: true takes the access away; sandboxes the service created stay as they are, and Deploy never stops or deletes them. In an environment registered before sandbox access existed, a deployment of a file with sandboxes: true fails until the environment’s services boundary is updated. After that failure, the stack’s Settings offers Update services boundary for the environment (it needs policies.update); then deploy again.

sandboxImages are images for those sandboxes, built from the repository with the services on every deployment and pushed to Container Registry under ci.registry (which the file then needs). Each is built from exactly one of source (with build overrides, but no startCommand: a sandbox has no start command) or dockerfile. A service passes one to its code as an env reference:

services:
  agents:
    type: web
    source: ./
    port: 4111
    sandboxes: true
    env:
      SANDBOX_IMAGE: ${{ sandboxImages.python.image }}

sandboxImages:
  python:
    dockerfile: ./sandbox/python.Dockerfile

A sandbox image that fails to build fails the deployment, and a rollback restores the sandbox images with the services’ images. An environment’s overrides can change a sandbox image’s build, but not add one. See Deploy a Mastra app.

Environment variables

Every service gets these, in addition to its env (the last two from its next deployment):

Variable Value
EZGH_ORGANIZATION The organization’s ID, org_…
EZGH_PROJECT The environment’s project ID, prj_…
EZGH_DEPLOY_ENVIRONMENT The environment’s name, such as production
NODE_EXTRA_CA_CERTS A file holding the EZGH database certificate authority, so Node trusts it
PGSSLROOTCERT The same file, on a service that references a database

Names starting EZGH_ are set by Deploy, and the file can’t set them. A NODE_EXTRA_CA_CERTS or PGSSLROOTCERT the file sets wins. A service that references a database and also connects to a PostgreSQL elsewhere with sslmode=require, through libpq or pgx, sets PGSSLROOTCERT itself or adds sslrootcert=system to that connection string, since libpq and pgx then check that server against this file.

Secrets

secrets.<name>.fields lists a secret’s fields in EZGH Secrets. Values never go in the file: set them in Secrets. generate creates a field with a random value of the given length on the first deployment when it’s absent. A deployment fails before it changes anything if a referenced field is missing.

Environments and overrides

Each entry under environments names a branch and a project (its prj_ ID or its name), which must match the environment’s registration. approve: true makes every plan wait for a person’s approval.

Each environment is a full copy of the stack in its own project. overrides changes it for that environment: a deep merge onto services, resources and runtime, where a list replaces the whole list. An override can change a service or resource the base has, but it can’t add one, remove a setting, or change a resource’s type.

Removing things

A service removed from the file is torn down. A resource removed from the file is detached: Deploy stops managing it and leaves it, with its data, as it is. Only ezgh deploy resources delete deletes one. See Managed resources.

Not available

Not available Instead
Bucket lifecycle rules Set them on the bucket’s own page; Deploy leaves fields the file doesn’t set as they are. See Lifecycle rules.
S3 access keys for services Services reach buckets through the Object Storage API as their own bot. For an S3 key, create one yourself and reference it as a secret.
A runtime.image other than linux/ubuntu:24.04 –

A file that sets any of these is refused with a message saying so.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close