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.

​
Prerequisites

  • Docker with buildx
  • BuildCharts installed
  • A repository root that contains a .sln or .slnx files

​
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
TargetDescription
buildglobal.json or target frameworks help determine the .NET SDK base image version
testTest package references such as Microsoft.NET.Test.Sdk, xunit, or nunit
nugetPackage metadata such as <PackageId> or <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
dockerA local Dockerfile in a project folder

​
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: 
# 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
You must define exactly one build target.

​
Parallelization: multiple targets vs dotnet test

build and test can also be placed 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, tests for the same project run in parallel across different target frameworks.

​
Create a lock file (optional)

Pin chart digests to make generation repeatable and avoid accidental drift. When a lock file is present, buildcharts generate checks for mismatches against charts/buildcharts/Chart.yaml before generating the build plan. For details, see Lock files. Create the lock file with: 
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

​
Signature verification (optional)

The built-in .NET charts are published as OCI artifacts and signed with Cosign in GitHub Actions. You can verify a chart signature before using or trusting a chart digest. Install cosign and verify the chart by digest: 
cosign verify \
  --certificate-identity-regexp 'https://github\.com/buildcharts/charts/\.github/workflows/.+' \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  docker.io/buildcharts/<chart>@sha256:<digest>
When using a lock file, the digest is available in charts/buildcharts/Chart.lock. That makes the lock file the natural source for verification input during CI or review.

​
Next steps

Last modified on May 3, 2026