> ## 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

> Reusable, versioned pipeline templates distributed as OCI artifacts.

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:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
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](https://github.com/dependabot) and [Renovate](https://github.com/renovatebot/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`:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
dependencies:
  - name: dotnet-docker
    alias: docker
    version: 0.0.2
    repository: oci://registry-1.docker.io/buildcharts
```

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
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:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
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:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
docker login <REGISTRY>
```

### Pull a chart directly

Use `buildcharts pull` to inspect a single chart:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts pull oci://registry-1.docker.io/buildcharts/dotnet-build:0.0.1 --untar
```

You can also pull by digest:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
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](/core-features/lock-files).

## What OCI means here

BuildCharts stores and pulls charts as OCI artifacts from a container registry.

OCI is the [Open Container Initiative](https://opencontainers.org/). 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](https://oras.land/).

BuildCharts uses the [ORAS C# client library](https://github.com/oras-project/oras-dotnet) 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](https://github.com/Azure/acr/blob/main/docs/container-registry-oras-artifacts.md).

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](https://oras.land/)                      | General OCI artifact workflows and registry operations         |
| [Helm](https://helm.sh/docs/topics/registries/) | Helm-style charts in OCI registries                            |
| [Kustomizer](https://kustomizer.dev/)           | Packaging and publishing Kubernetes manifests as OCI artifacts |

ORAS is a common choice when you want a more general OCI artifact workflow. See [ORAS](https://oras.land/) 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`](/core-features/lock-files) 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](https://github.com/notaryproject/notation)      | A CLI from the Notary Project for attaching and verifying OCI artifact signatures as first-class registry metadata.    |
| [Cosign](https://github.com/sigstore/cosign)               | A Sigstore CLI for signing and verifying OCI artifacts, often paired with keyless or key-based supply-chain workflows. |
| [Helm provenance](https://helm.sh/docs/topics/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 builds](/core-features/docker-builds).

### 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

* [Handle dependencies](/charts/handle-dependencies)
* [Lock files](/core-features/lock-files)