---
title: "The build file"
description: "Every key of .ezgh/build.yaml, the rules the format keeps, its limits and how errors are reported."
---

> 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 build file

The build file is `.ezgh/build.yaml` at the repository's root, read at the pushed commit. Its JSON
Schema is at `https://build.ezghcloud.com/schema/v1.json`.

## Top level

| Key | Meaning |
| --- | --- |
| `version` | Required. Always `1` |
| `trigger` | Required. Which pushed refs start a pipeline: `branches` and `tags`, each a list of globs over names (`main`, `release/*`, `v*`). At least one of the two |
| `tasks` | Required. 1 to 100 tasks by name. A name is a lowercase letter, then up to 39 lowercase letters, digits or `-` |

## Task keys

| Key | Meaning |
| --- | --- |
| `needs` | Tasks that must succeed first. The only ordering: there are no stages |
| `run` | Shell text, run by `/bin/sh -eu` in `/workspace`. A task has exactly one of `run` and `build` |
| `build` | The built-in [image build](/build/image-builds): `dockerfile`, `repository` and optional `tags`. Needs `bot`; takes no `image`, `run`, `outputs` or `warm` |
| `image` | Required with `run`: a repository path on the project's registry host, with an optional `:tag` or `@sha256:…` digest. Docker Hub images come through a [pull-through cache rule](/registry/pull-through-cache), as in `hub/library/golang:1.25` |
| `inputs` | Globs of repository files the task may read. Only these are placed in `/workspace`. Left out, it is the whole repository; `[]` is none. A glob that matches a directory matches everything beneath it |
| `outputs` | Absolute paths saved when the task succeeds and restored, at the same paths, into every task that needs it. Not globs |
| `warm` | Absolute scratch paths, such as compiler and package caches, restored from the newest trusted run of this task and saved again by trusted runs |
| `cache` | `false` makes the task always run. Must be written, `true` or `false`, on a task that names `clusters`. Default `true` |
| `only` | `branches` and `tags` globs. On other refs the task is skipped, and so is every task that needs it |
| `size` | `small` (1 vCPU, 2 GiB), `medium` (2 vCPUs, 4 GiB; the default), `large` (4, 8) or `xlarge` (8, 16) |
| `disk_gib` | Disk in GiB, 1 to 50. Default 10 |
| `timeout` | A whole number and `s`, `m` or `h` (`90s`, `15m`, `2h`). Default `15m`, at most `6h` |
| `env` | Literal text values by variable name. Names starting `EZGH_` are set by EZGH Build |
| `bot` | The bot the script acts as, by name or ID ([Bots and trust](/build/bots-and-trust)) |
| `secrets`, `buckets`, `clusters` | Resources the task is given, as its bot ([Secrets, buckets and clusters](/build/resources)). Each needs `bot` |

`build` takes `dockerfile` (the Dockerfile's path in the repository), `repository`
(`<scope>/<image>` in the project's registry) and `tags` (extra literal tags).

## Globs

`*` matches within one `/`-separated segment. `**` is a whole segment and matches any number of
segments. `?`, `[`, `]`, `{`, `}`, `!` and `\` are not supported. A glob has at most 32 segments,
four `*` in a segment and two `**`, and is at most 256 bytes. `inputs` globs are relative to the
repository's root.

## Rules

- **Plain YAML, read strictly.** Anchors, aliases, merge keys, tags, a second document, duplicate
  keys and unknown keys are refused.
- **Quote text that looks like a number or a boolean.** `image: 1.20` and `tags: [no]` are errors
  that say to quote the value; nothing is converted silently.
- **Nothing is substituted into the file.** There is no expression language and nothing to include
  or import. Values reach a script only as environment variables.
- **One ordering.** Tasks are ordered by `needs` alone.

## Limits

| Limit | Value |
| --- | --- |
| File size | 256 KiB |
| Tasks | 100 |
| Items in a list (`needs`, `inputs`, `outputs`, `warm`, `tags`, `buckets`, `clusters`, `branches`) | 64 |
| A glob or path | 256 bytes |
| Tasks running at once | 20 in an organization |
| A task's log | 16 MiB, kept 90 days |

## Environment

Every task's script has:

| Variable | Value |
| --- | --- |
| `EZGH_ORGANIZATION`, `EZGH_ORG` | The organization's ID |
| `EZGH_PROJECT` | The project's ID |
| `EZGH_REPOSITORY` | The repository |
| `EZGH_REGISTRY` | The project's registry host |
| `EZGH_TASK` | The task's name |
| `EZGH_TASK_<NAME>_IMAGE` | For each `build` task it needs: `host/repository@sha256:…` of the image that task built. `<NAME>` is the task's name in capitals, `-` as `_` |

Tasks with `cache: false` also have `EZGH_COMMIT_SHA`, `EZGH_REF` and `EZGH_PIPELINE_ID`. A task that
may be reused doesn't: it would carry another commit's values. Under `sh -eu`, reading one that isn't
set fails the script.

A task with a `bot` also has `EZGH_API_KEY` ([Bots and trust](/build/bots-and-trust)).

## Errors

`ezgh build validate` and [ValidateFile](/build-api/ValidateFile/) report every problem with
its place in the file, the reason and an example that would be accepted:

```text
tasks.rollout
  a task that names clusters must say cache: true or cache: false
  Example: cache: false
tasks.rollout.image
  1.20 is read as a number, not text; quote it
  Example: image: "1.20"
```

The format is checked without a request. What the file names is checked in two places:

- `ezgh build validate`, when you are logged in, looks up each bot, secret, bucket, cluster and
  image with your own credential.
- When a task runs, its bot reads what the task names. A name that doesn't exist, or that the bot
  may not use, fails the task before its script starts.

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