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.

​
File layout

BuildCharts uses separate files for separate concerns.
  • build.yml defines repository-local build intent: targets, types, variables, and optional plugins.
  • charts/buildcharts/Chart.yaml maps those target types to versioned OCI-hosted chart implementations.
  • charts/buildcharts/Chart.lock optionally pins the resolved chart digests for repeatability and drift detection.
This separation is deliberate. Repositories declare what should be built. Shared charts define how it is implemented. Docker Buildx Bake remains the execution layer.

​
build.yml

This file defines variables, plugins, targets, and optional type matrices. Each target declares a type, but BuildCharts does not implement that type directly. Instead, it uses the type as an alias lookup into charts/buildcharts/Chart.yaml. Example: 
version: v1beta

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

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

  src/App/App.csproj:
    type: docker
    with:
      base: mcr.microsoft.com/dotnet/runtime:10.0
      tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]
These rules matter on every run:
  • Exactly one build target must be defined.
  • Every target type must match an alias declared in charts/buildcharts/Chart.yaml.
  • Plugins run during generation, not during Bake execution.

​
charts/buildcharts/Chart.yaml

This file maps each target alias to a versioned OCI chart. The alias is the contract between repo-local intent and shared implementation. 
dependencies:
  - name: dotnet-build
    alias: build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts
Running buildcharts update resolves those dependencies and can record the resolved digests in Chart.lock.

​
charts/buildcharts/Chart.lock

This file is optional. When it exists, buildcharts generate validates it against Chart.yaml and the registry digest unless --ignore-lock is used. This keeps chart version selection flexible in Chart.yaml while still pinning the exact artifact used during generation. Example: 
dependencies:
  - name: dotnet-build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts/dotnet-build
    digest: sha256:...
lockVersion: 1

​
Generation flow

During buildcharts generate, BuildCharts acts as a generator:
  1. It removes the previous .buildcharts output.
  2. It reads build.yml, Chart.yaml, and Chart.lock if it exists.
  3. It validates the build target count, target aliases, and lock file state.
  4. It pulls or reuses the OCI chart artifacts referenced by Chart.yaml.
  5. It materializes chart contents under .buildcharts.
  6. It runs each configured plugin.
  7. It writes .buildcharts/docker-bake.hcl.
The important boundary is that BuildCharts stops after generation. The generated HCL and Dockerfiles are the handoff to Docker tooling.
With --use-inline-dockerfiles, the generated HCL embeds chart Dockerfiles instead of referencing files under .buildcharts/<chart-name>/Dockerfile. That can make the generated plan easier to move around as a single artifact.

​
Execution flow

After generation, execution flows through Docker Buildx Bake and BuildKit:
  • BuildCharts writes the generated HCL.
  • Docker Buildx Bake reads the generated Bake file.
  • BuildKit executes the selected targets.
# Run default group target
docker buildx bake --file .buildcharts/docker-bake.hcl

# Run specific target
docker buildx bake --file .buildcharts/docker-bake.hcl test
From there, Docker builds covers execution options, Exporting build artifacts covers output behavior by target type, and Examples shows complete workflows.
Last modified on May 3, 2026