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.

Charts are used for build composition and distributed using OCI-registries.

​
What charts mean in BuildCharts

Charts are how BuildCharts separates build intent from build implementation:
  • Build intent stays in build.yml
  • Charts define how each stage runs
That lets multiple repositories share the same versioned stage implementations without copying pipeline logic into every repository. You can think of charts as OCI-versioned stages in a centrally managed multi-stage build model. Each chart dependency provides the implementation for a stage type such as build, test, nuget, or docker, and repositories opt into those stages by alias instead of embedding the stage logic themselves. That central model matters when you want to manage pipeline behavior across many repositories. You can update the chart once, publish a new version, and let repositories adopt that version through normal dependency updates instead of editing CI definitions repo by repo. This is similar to Helm charts in one important way: both use versioned chart metadata and both can be distributed through OCI registries. Like Helm charts, BuildCharts charts are versioned packages you can manage centrally and consume from many repositories. The difference is what the chart configures. Helm charts describe how an application is deployed to Kubernetes. BuildCharts charts describe how build stages are generated into a Docker Bake plan for CI and local builds.

​
Declare stage aliases in Chart.yaml

BuildCharts uses a Helm chart file with dependency aliases: 
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-test
    alias: test
    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-docker
    alias: docker
    version: 0.0.2
    repository: oci://registry-1.docker.io/buildcharts
Each dependency needs:
  • name
  • alias
  • version
  • repository
BuildCharts turns that into a chart reference in the form repository/name:version.

​
Governance with dependency automation

Because chart dependencies are declared in charts/buildcharts/Chart.yaml, teams can use existing dependency tooling such as Dependabot and Renovate to automate update PRs. In practice, this lets you centralize build-stage governance in chart versions and let automation open PRs when new chart releases are available. That enables controlled rollouts where each team can adopt a new version through a normal review flow, with an update PR that can include context such as release notes and a summary of what changed in the pipeline. If a chart release updates underlying Docker images or build logic, repositories can adopt that change through a standard dependency update workflow.

​
Alias mapping

Each dependency declares an alias that you use in build.yml: 
dependencies:
  - name: dotnet-docker
    alias: docker
    version: 0.0.2
    repository: oci://registry-1.docker.io/buildcharts

targets:
  src/App/App.csproj:
    type: docker
If docker is not declared as an alias in Chart.yaml, buildcharts generate fails.

​
Container registry

Each chart dependency in charts/buildcharts/Chart.yaml points to a repository in an OCI-compliant container registry: 
repository: oci://registry-1.docker.io/buildcharts
That registry is the dependency source for the chart. BuildCharts does not call a separate backend or package server. When you run buildcharts update, buildcharts pull, or buildcharts generate, BuildCharts resolves the chart manifest and pulls the chart blob from that registry. That also means authentication is registry authentication. You authenticate to the container registry that stores the chart, such as:
  • Docker Hub (docker.io)
  • GitHub Container Registry (ghcr.io)
  • Azure Container Registry (<registry-name>.azurecr.io)
  • Another OCI-compatible registry

​
Authenticate to private registries

BuildCharts uses the same credential model as Docker. Authenticate with the standard Docker login flow: 
docker login <REGISTRY>

​
Pull a chart directly

Use buildcharts pull to inspect a single chart: 
buildcharts pull oci://registry-1.docker.io/buildcharts/dotnet-build:0.0.1 --untar
You can also pull by digest: 
buildcharts pull oci://registry-1.docker.io/buildcharts/dotnet-build@sha256:...

​
Lock files

For digest pinning, repeatable chart resolution, and lock validation during generation, see Lock files.

​
What OCI means here

BuildCharts stores and pulls charts as OCI artifacts from a container registry. OCI is the Open Container Initiative. OCI defines open specifications around container formats and distribution. The parts that matter most here are:
  • The OCI Image Specification, which defines how manifests, layers, descriptors, and media types are represented
  • The OCI Distribution Specification, which defines how clients push and pull content from registries
In practice, this is why BuildCharts can treat a chart as content stored in the same kind of registry infrastructure that teams already use for container images. Using OCI-hosted charts gives BuildCharts a few practical benefits:
  • Versioned stage implementations that can be shared across many repositories
  • Digest pinning through Chart.lock
  • Reuse of existing registry infrastructure, permissions, and auth flows
  • A portable distribution format instead of a custom package server
  • Compatibility with general OCI tooling and OCI-native workflows

​
What ORAS is doing here

ORAS stands for OCI Registry As Storage. BuildCharts uses the ORAS C# client library to talk to the registry and pull chart content. In practice, buildcharts acts as an embedded ORAS client when it consumes charts:
  • The chart is stored in the registry as an OCI artifact
  • BuildCharts resolves the manifest and digest
  • BuildCharts fetches the chart blob
  • BuildCharts unpacks it into .buildcharts
ORAS itself is a CLI and set of client libraries for working with OCI artifacts in OCI-compliant registries. The important part here is that it works with general OCI artifacts, not only with container images. If you want a registry-specific example of ORAS artifacts in practice, see Azure ACR ORAS artifacts. You do not need to install the ORAS CLI yourself to use BuildCharts. Registry access is already built into the buildcharts CLI.

​
ORAS-compliant CLIs

BuildCharts is also not tied to ORAS as the publishing tool. It consumes OCI artifacts by registry, repository, tag, and digest, so teams can publish compatible chart artifacts with ORAS, Helm, or another OCI-capable CLI. Examples of OCI-capable CLIs in this ecosystem:
CLITypical use
ORASGeneral OCI artifact workflows and registry operations
HelmHelm-style charts in OCI registries
KustomizerPackaging and publishing Kubernetes manifests as OCI artifacts
ORAS is a common choice when you want a more general OCI artifact workflow. See ORAS for the underlying registry client model.

​
Trust and integrity

If you want to secure your chart supply chain, treat charts like other OCI artifacts. This section is about securing the published BuildCharts OCI templates themselves: who published them, what content was published, and what policy decides whether they are trusted for use. The practical baseline is:
  • Store charts in a controlled container registry
  • Sign published chart artifacts
  • Verify signatures and trust policy when consuming
  • Consume immutable artifact references where possible (digest pinning)

​
Digest pinning

Chart.lock is the first line of defense. It pins the resolved digest for each chart dependency so buildcharts generate can detect drift between:
  • Chart.yaml
  • Chart.lock
  • The current registry manifest digest
That improves reproducibility, but digest pinning alone does not prove who published the artifact.

​
Signing

BuildCharts does not implement its own signing or trust system. BuildCharts does not sign charts itself. If you need signed charts, use OCI-native signing tools and verify signatures during promotion or consumption.
ToolDescription
NotationA CLI from the Notary Project for attaching and verifying OCI artifact signatures as first-class registry metadata.
CosignA Sigstore CLI for signing and verifying OCI artifacts, often paired with keyless or key-based supply-chain workflows.
Helm provenanceHelm’s chart signing and provenance model for proving chart origin and integrity in Helm-based workflows.

​
Repository governance

Trust and integrity also depend on how your chart source is managed before publication. A practical governance model is to keep BuildCharts OCI templates in a dedicated repository and protect that repository with:
  • Branch protection
  • Required pull requests
  • Mandatory reviews
  • Controlled publishing to the target registry
That gives teams one central place to review and approve changes to shared build logic before those changes are published and consumed by many repositories.

​
Validation and scanning

It is also useful to enforce automated quality gates before publishing chart artifacts. Typical checks include:
  • CI validation for chart packaging and publishing rules
  • Dockerfile linting
  • Static analysis
  • Policy checks
  • Central Dockerfile and image scanning
This is one of the main benefits of centralized charts. Instead of relying on every application repository to enforce the same checks, platform teams can validate and scan shared OCI templates once in the chart pipeline and publish only approved versions. For produced images and build outputs, provenance and SBOM belong in the Docker Buildx execution layer rather than the chart distribution layer. See Docker builds. A practical model for teams using private or shared charts is:
  1. Publish charts to a controlled OCI registry.
  2. Sign the published chart artifacts with Notation or Cosign.
  3. Pin digests in Chart.lock.
  4. Verify signatures before promotion or consumption.
  5. Generate provenance and SBOM attestations for produced images in the Buildx layer.

​
What BuildCharts does not do

BuildCharts intentionally does not:
  • Sign charts
  • Verify signatures
  • Manage trust stores or policy
  • Generate SBOMs for pulled chart artifacts
Those controls belong in your chart publishing pipeline, registry policy, and image build policy.
Last modified on May 3, 2026