Skip to main content
buildcharts turns repo-local metadata into a docker buildx bake plan.

​
Inputs

​
build.yml

This file defines variables, plugins, targets, and optional type matrices. Two rules matter on every run:
  • You must define exactly one build target.
  • Every target type must match an alias declared in charts/buildcharts/Chart.yaml.

​
charts/buildcharts/Chart.yaml

This file maps each target alias to a versioned OCI chart. 
dependencies:
  - name: dotnet-build
    alias: build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

​
charts/buildcharts/Chart.lock

This file is optional. When it exists, buildcharts generate validates it against Chart.yaml and the registry digest unless you pass --ignore-lock.

​
What buildcharts generate does

  1. Cleans .buildcharts from the previous run.
  2. Reads build.yml, Chart.yaml, and Chart.lock if it exists.
  3. Validates the build target count, target aliases, and lock file state.
  4. Pulls chart artifacts into .buildcharts.
  5. Runs each plugin in plugins.
  6. Writes .buildcharts/docker-bake.hcl.
If you use --use-inline-dockerfiles, the generated HCL embeds chart Dockerfiles instead of referencing files under .buildcharts/<chart-name>/Dockerfile.

​
What docker buildx bake does next

BuildCharts generates one Bake target per type. You can run the default group or a single type such as docker buildx bake test. The generated outputs depend on the type:
  • build targets use type=cacheonly
  • docker targets use type=docker
  • Every other type exports to .buildcharts/output/<type>
That export layout is why the samples can read test results from .buildcharts/output/test and NuGet packages from .buildcharts/output/nuget.

​
Why Bake helps

Bake is a strong execution layer for CI/CD and monorepos because it can:
  • parallelize independent targets (for example building multiple services, running tests, and packaging in one run)
  • reduce duplicated context transfers across targets, which matters on remote builders and in CI
  • reuse BuildKit caching and cache exports/imports to reduce build times across repeated runs
  • model complex build graphs declaratively with groups, targets, matrices, and --set overrides
This helps teams maintain consistent build execution across dozens or hundreds of services without copy-pasting and drifting CI configuration.

​
Scope

BuildCharts is a build-plan generator. It does not replace your CI/CD platform. BuildCharts also does not:
  • manage deployments or runtime configuration
  • host secrets or artifacts for you
  • package or publish charts/templates for you
  • provide a built-in signing or trust system for charts

​
When it fits

BuildCharts tends to fit well when you:
  • already use Docker and BuildKit for builds
  • want to centralize build logic across many repositories
  • want the same build plan to run locally and in CI
  • benefit from parallel builds and BuildKit caching

​
When it doesn’t

BuildCharts tends to be a poor fit when you:
  • cannot run Docker daemons or BuildKit in your environment
  • have highly bespoke build steps that do not map well to Docker-based stages
  • have very constrained runners where Bake parallelism and caching add more overhead than benefit
Last modified on March 15, 2026