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:
- PHP:
composer.jsonorindex.php - Go:
go.mod - Python:
requirements.txt,pyproject.toml,Pipfile,uv.lockorpoetry.lock - Node:
package.json, with npm, pnpm, Yarn or Bun - A static site:
index.html - Anything else, when
build.startCommandis 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 asshop/imgproxy:v3;<prefix>/<namespace>/<name>under an active pull-through cache rule, such ashub/library/nginx:1.27for Docker Hub’snginx: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.DockerfileA 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.