Charts

Reusable, versioned pipeline templates distributed as OCI artifacts.

BuildCharts resolves stage implementations from OCI-hosted charts declared in charts/buildcharts/Chart.yaml.

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. If a chart release updates underlying Docker images or build logic, repositories can adopt that change through a standard dependency update workflow instead of manual CI edits.

What charts mean in BuildCharts

Charts are how BuildCharts separates build intent from build implementation:

• build.yml says what to build
• charts say how that 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.

Pull a chart directly

Use buildcharts pull when you want 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:...

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 BuildCharts backend or package server. When you run buildcharts update, buildcharts pull, or buildcharts generate, BuildCharts resolves the chart reference against that registry and pulls the chart content from there.

That also means authentication is registry authentication. You authenticate to the container registry that stores the chart, such as:

• Docker Hub
• GitHub Container Registry (ghcr.io)
• Azure Container Registry
• another OCI-compatible registry

Authenticate to private registries

If the registry is public, BuildCharts can pull the chart without credentials. If the registry is private, buildcharts pull, buildcharts update, and buildcharts generate need valid registry credentials before BuildCharts can resolve the manifest or pull the chart blob.

BuildCharts reuses the existing Docker credential model.

It reads Docker config from:

• <DOCKER_CONFIG>/config.json (override location with DOCKER_CONFIG)
• ~/.docker/config.json

The current implementation supports:

• credHelpers
• auths
• credsStore

That means the common path is:

• authenticate to the registry with Docker or the registry’s normal Docker-compatible login flow
• let Docker write credentials or helper configuration
• run buildcharts and let it reuse those credentials

This also covers external Docker credential helpers. If Docker is configured to use a helper, BuildCharts uses the same helper.

Azure Container Registry is also handled explicitly in the current implementation. BuildCharts supports the Azure-style token shapes that appear in Docker config and helper output for .azurecr.io, so Azure-backed Docker auth flows continue to work as long as the credentials end up in Docker’s config or helper chain.

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.

Lock files

BuildCharts supports an optional charts/buildcharts/Chart.lock file for more repeatable builds.

When you run buildcharts update, BuildCharts resolves chart digests and writes that lock file.

If the lock file exists, buildcharts generate uses it to detect dependency drift before it renders the Bake plan. If the lock file and the resolved chart state do not match, generation stops with a discrepancy warning and tells you to refresh the lock file. If it does not exist, generation still works, but chart resolution follows the current registry tags instead of pinned digests.

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.

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:

CLI	Typical use
ORAS	General OCI artifact workflows and registry operations
Helm	Helm-style charts in OCI registries
Kustomizer	Packaging 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.

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.

Why this model is useful

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

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.

Tool	Description
Notation	A CLI from the Notary Project for attaching and verifying OCI artifact signatures as first-class registry metadata.
Cosign	A Sigstore CLI for signing and verifying OCI artifacts, often paired with keyless or key-based supply-chain workflows.
Helm provenance	Helm’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 Bake.

Recommended model

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.

Related pages

• Lock files
• Handle dependencies