Skip to main content

Documentation Index

Fetch the complete documentation index at: https://buildcharts.dev/llms.txt

Use this file to discover all available pages before exploring further.

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: 
# yaml-language-server: $schema=https://raw.githubusercontent.com/buildcharts/buildcharts/main/schemas/v1beta.json

​
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: 
variables:
  - VERSION
  - COMMIT

variables:
  - VERSION: "1.0.0-local"
  - COMMIT: ""

variables:
  - VERSION:
      default: "1.0.0-local"
  - COMMIT: ""

variables:
  VERSION: "1.0.0-local"
  COMMIT: ""

​
plugins

Optional list of plugin names: 
plugins:
  - NuGetAuthenticate@v1
  - TestcontainersDinD@v1

​
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: 
targets:
  buildcharts.sln: build
Mapping with one type: 
targets:
  src/App/App.csproj:
    type: docker
    with:
      base: mcr.microsoft.com/dotnet/runtime:10.0
      tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]
Mapping with multiple types that share the same with block: 
targets:
  src/App/App.csproj:
    type: [build, test]
    with:
      base: mcr.microsoft.com/dotnet/sdk:10.0
Sequence of entries: 
targets:
  src/App/App.csproj:
    - type: build
      with:
        base: mcr.microsoft.com/dotnet/sdk:10.0

    - type: docker
      with:
        base: mcr.microsoft.com/dotnet/runtime:10.0
        tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]

​
types

Optional type-level matrix expansion. Use types.<type>.matrix when you want to expand every target of a given type across one or more axes: 
types:
  docker:
    matrix:
      platform: ["linux/amd64", "linux/arm64"]
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: 
targets:
  src/dotnet-krp/dotnet-krp.csproj:
    - type: publish

types:
  publish:
    matrix:
      runtime: ["win-x64", "win-arm64"]
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.
KeyEffect
baseAdds a named base context using docker-image://...
tagsSets Bake tags for the generated target
dockerfileOverrides the default chart Dockerfile path
allowSets BuildKit entitlements such as network.host
argsAdds per-target build args
Notes:
  • 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

# yaml-language-server: $schema=https://raw.githubusercontent.com/eddietisma/buildcharts/main/schemas/v1beta.json

version: v1beta

variables:
  VERSION: "1.0.0"
  COMMIT: "local"

targets:
  buildcharts.sln:
    type: build
    with:
      base: mcr.microsoft.com/dotnet/sdk:10.0

  src/BuildCharts.Tool/BuildCharts.Tool.csproj:
    - type: nuget
    - type: docker
      with:
        base: mcr.microsoft.com/dotnet/runtime:10.0
        tags: ["docker.io/buildcharts/buildcharts:${VERSION}-${COMMIT}"]

  tests/BuildCharts.Tool/BuildCharts.Tests.csproj:
    type: test
Last modified on April 22, 2026