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: 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, 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) |
secrets, buckets, clusters |
Resources the task is given, as its bot (Secrets, buckets and clusters). 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.20andtags: [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
needsalone.
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).
Errors
ezgh build validate and ValidateFile report every problem with
its place in the file, the reason and an example that would be accepted:
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.