Define build stages

Model build, test, package, and image stages with BuildCharts target definitions.

Use targets in build.yml to describe the stages BuildCharts should generate.

Start with one build stage

Every build.yml must contain exactly one target with type: build.

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

BuildCharts validates this rule during buildcharts generate.

Add more stages to a project

A project can declare multiple stages by using a sequence:

targets:
  src/App/App.csproj:
    - type: build
      with:
        base: mcr.microsoft.com/dotnet/sdk:10.0
    - type: test
      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}"]

Each type must match an alias in charts/buildcharts/Chart.yaml.

Use built-in target variables

Every generated target gets a small set of built-in build args automatically.

For example:

targets:
  src/MyApp/MyApp.csproj:
    type: build

BuildCharts injects:

Variable	Meaning
BUILDCHARTS_SRC	The target source path, for example src/MyApp/MyApp.csproj
BUILDCHARTS_TYPE	The generated target type, for example build

Charts can use these variables inside their Dockerfiles and build logic. BUILDCHARTS_SRC lets a chart know which source entry it is building, and BUILDCHARTS_TYPE identifies the resolved stage type behind the chart alias.

Reuse one with block across multiple stages

If stages share the same configuration, use type: [build, test]:

targets:
  src/App/App.csproj:
    type: [build, test]
    with:
      base: mcr.microsoft.com/dotnet/sdk:10.0

BuildCharts expands that into two stage definitions internally.

Pass stage-specific settings

The current generator recognizes these keys under with:

Key	What it controls
base	Named base image context
tags	Image tags for docker stages
dockerfile	Override the chart Dockerfile path
allow	BuildKit entitlements
args	Build args passed into the chart

Example:

targets:
  src/Library/Library.csproj:
    - type: nuget
      with:
        args:
          SOURCELINK_STRICT: 0

    - type: docker
      with:
        base: mcr.microsoft.com/dotnet/runtime:10.0
        dockerfile: ./Dockerfile
        allow: ["network.host"]
        tags: ["docker.io/example/library:${VERSION}-${COMMIT}"]

Custom build arguments

You can define custom ARG values in chart Dockerfiles and pass values from build.yml through with.args.

Dockerfile example:

ARG SOURCELINK_STRICT=1

build.yml example:

targets:
  src/Library/Library.csproj:
    - type: nuget
      with:
        args:
          SOURCELINK_STRICT: 0

BuildCharts writes these values into the generated Bake target, so the chart Dockerfile receives them as standard build args at execution time.

Expand a stage with a matrix

Use types when every target of the same type should fan out across a matrix:

types:
  docker:
    matrix:
      platform: ["linux/amd64", "linux/arm64"]

Each matrix axis is expanded into multiple generated Bake variants for that type, and every axis value is exposed to the chart as an uppercase build arg.

For example, this metadata:

targets:
  src/dotnet-krp/dotnet-krp.csproj:
    - type: publish

types:
  publish:
    matrix:
      runtime: ["win-x64", "win-arm64"]

becomes a generated Bake matrix for publish where:

• the same source target is reused
• the runtime axis expands into one variant per value
• the generated target name includes the matrix value
• the chart receives RUNTIME as a build arg

In practice, that one type: publish entry turns into two generated publish variants, one for win-x64 and one for win-arm64.

This is conceptually similar to:

• Azure DevOps strategy matrix
• GitHub Actions matrix strategy

The difference is that BuildCharts expands the matrix into Docker Buildx Bake targets instead of CI jobs. The matrix values become Bake target variants and build args that your chart Dockerfiles can consume.

Read more about Docker matrix targets.