Skip to content

The build file

Every key of .ezgh/build.yaml, the rules the format keeps, its limits and how errors are reported.

Updated View as Markdown

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

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

Type to search…

↑↓ navigate↵ selectEsc close