Skip to main content
Use build.yml to describe what your repository should build. The generator reads this file from the repository root.

​
Schema

Use the shipped schema for editor validation:

​
Top-level fields

​
version

String value for the config version. The repository samples use v1beta.

​
variables

Variables become Bake variables and are also exposed through the generated _common target args. Supported forms:

​
plugins

Optional list of plugin names:

​
targets

Required mapping of source path to one or more target definitions. You must define exactly one build target across the whole file. Supported forms: Single scalar:
Mapping with one type:
Mapping with multiple types that share the same with block:
Sequence of entries:

​
types

Optional type-level contexts and matrix expansion. Use types.<type>.contexts when every generated target of the same type should receive the same Docker Bake named context:
Use types.<type>.matrix when you want to expand every target of a given type across one or more axes:
Every target of that type is expanded across the matrix axes. Each axis value is exposed to the chart as an uppercase snake case build arg. For example, this metadata:
produces one generated Bake target per matrix value. In the generated docker-bake.hcl, the publish target becomes a Bake matrix with:
  • One item entry for the source target
  • One runtime axis with both values
  • A target name pattern such as ${item.name}_${runtime}
  • An injected build arg RUNTIME="${runtime}"
That means a single type: publish definition expands into two generated publish variants, one for win-x64 and one for win-arm64.

​
Target keys

​
with

Each target can define these supported options under with. Notes:
  • contexts is a mapping of HCL identifier names to non-empty context values.
  • Use docker-image://... when a chart Dockerfile expects a named image context such as base.
  • The context name build is reserved. BuildCharts automatically wires non-build targets to target:build.
  • args values can be strings or arrays
  • Array values are emitted as comma-separated strings in the generated HCL
  • If you omit dockerfile, BuildCharts uses ./.buildcharts/<chart-name>/Dockerfile

​
Alias resolution

Each target type must match an alias in charts/buildcharts/Chart.yaml. If you define type: publish, you also need a chart dependency whose alias is publish.

​
Example

Last modified on June 2, 2026