---
title: "The EZGHDeploy file"
description: "Services, resources, secrets and environments in EZGHDeploy, how references wire them together, and the file's limits."
---

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

# The EZGHDeploy file

`EZGHDeploy` sits at the root of the repository. Each environment reads it from its own branch.
Every key is listed in the [file reference](/deploy/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](/registry/pull-through-cache),
  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](/deploy/deployments#waiting-for-dns)).

### 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](/deploy/file-reference#references)
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](/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`](/sandboxes/bots) 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:

```yaml
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](/deploy/mastra).

## 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](/deploy/environments). `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](/deploy/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](/object-storage/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.

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