Skip to main content

​
Prerequisites

  • Docker with buildx
  • BuildCharts installed locally or globally
  • A repository root that contains a .sln or .slnx file if you want to use buildcharts init

​
Scaffold a repository

Run buildcharts init from the repository root. 
buildcharts init
In a .NET repository, this command:
  • Creates build.yml
  • Creates charts/buildcharts/Chart.yaml
  • Creates .github/workflows/buildcharts.yml when the Git remote points to GitHub
init currently supports .NET repositories only.

​
Use the built-in .NET charts

BuildCharts ships with first-class .NET charts for common stage types. These are a practical starting point when you want working defaults before you introduce your own chart ecosystem. The built-in .NET chart set is documented here: The shipped Dockerfiles cover the common .NET workflows:
  • build runs dotnet build
  • test runs dotnet test and prepares test artifacts
  • nuget runs dotnet pack and prepares package output
  • publish runs dotnet publish
  • docker publishes the app and assembles the runtime image
These charts are implemented as reusable Dockerfiles behind the chart aliases you reference from build.yml.

​
Dependency chart

apiVersion: v2
name: buildcharts
version: 0.0.1
description: A meta-chart to define build pipeline targets and templates
type: application

dependencies:
  - name: dotnet-build
    alias: build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-docker
    alias: docker
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-nuget
    alias: nuget
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-publish
    alias: publish
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts

  - name: dotnet-test
    alias: test
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts
This file maps target aliases in build.yml to the built-in .NET charts.

​
Review the generated metadata

This shape matches the shipped samples: 
version: v1beta

variables:
  - VERSION
  - COMMIT

targets:
  buildcharts.sln:
    - 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/buildcharts/buildcharts:${VERSION}-${COMMIT}"]

  test/BuildCharts.Tests/BuildCharts.Tests.csproj:
    type: test

  test/BuildCharts.Tests1/BuildCharts.Tests1.csproj:
    type: test
You must define exactly one build target.

​
Parallelization: multiple targets vs dotnet test

If you prefer, you can also put build and test directly on the solution target. This works well for .NET because dotnet build and dotnet test can run directly against a solution, so the solution can act as the shared source for both stages: 
targets:
  buildcharts.sln:
    type: [build, test]
    with:
      base: mcr.microsoft.com/dotnet/sdk:10.0
That shifts test parallelization to dotnet test, which then delegates to the test framework and runner, such as xUnit, NUnit, or MSTest. The tradeoff is execution strategy:
  • solution-level test keeps the config simpler and matches normal .NET workflows
  • separate test targets can let Docker Bake parallelize more work across targets
  • separate targets may also benefit differently from Docker layer caching
Which model is faster depends on your solution shape, test layout, hardware, number of tests, and how test assemblies are distributed, so benchmark both if build time matters.
From .NET 9, the same test project can run across different target frameworks in parallel through MSBuild.

​
Create a lock file

buildcharts generate works without charts/buildcharts/Chart.lock, but buildcharts update gives you pinned chart digests and lets generate detect drift. 
buildcharts update

​
Generate and run the plan

Bash: 
export VERSION=1.0.0
export COMMIT=$(git rev-parse HEAD)

buildcharts generate
docker buildx bake --file .buildcharts/docker-bake.hcl
PowerShell: 
$env:VERSION = "1.0.0"
$env:COMMIT = (git rev-parse HEAD)

buildcharts generate
docker buildx bake --file .buildcharts/docker-bake.hcl

​
Next steps

Last modified on March 15, 2026