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.

​
What BuildCharts is

buildcharts is a thin generation layer for standardized builds. Build intent is defined in build.yml, reusable chart implementations are resolved from versioned OCI-hosted charts, and the result is a generated Docker Buildx Bake plan for local or CI execution. It keeps repository configuration focused on what should be built, while shared charts define how each build stage runs. BuildCharts does not replace your CI system, container registry, or Docker toolchain.
If you already know Helm, the comparison is useful: both Helm and BuildCharts use versioned OCI charts. The difference is what the chart controls. Helm charts describe deployments to Kubernetes. BuildCharts describe build stages for Docker builds.

​
Problem domain

At scale, CI/CD systems tend to run into the same structural problems:
  • Pipeline YAML is duplicated across many repositories with minor variations.
  • Shared templates are hard to version, test, and roll out incrementally.
  • CI behavior often diverges from local developer workflows.
  • CI providers become tightly coupled to build logic.
  • Small pipeline changes can have a large blast radius.
  • Centralized YAML is hard to maintain without a clear rollout model.
The core issue is not a lack of CI tooling. It is the lack of a portable build abstraction that separates what a project needs to build from how that build is implemented.

​
Motivation

BuildCharts provides a portable way to move ad-hoc CI scripts, tool setup, and shared build logic into versioned chart Dockerfiles. Repositories keep lightweight build intent in build.yml, while the generated Docker plan can run locally or in CI with the same Docker tooling. The goal is a single, portable approach that replaces ad-hoc scripts with consistent Docker-based build steps while staying flexible and provider-agnostic.
For a deeper architectural discussion of the problem space, goals, trade-offs, and governance model, read the Assessment and Rationale on GitHub.

​
Workflow

src/
├── build.yml            # Build metadata
├── charts/
│   └── buildcharts/
│       ├── Chart.yaml   # Chart dependency data
│       └── Chart.lock   # Optional lock file
  1. Create build.yml and charts/buildcharts/Chart.yaml, or scaffold them with buildcharts init.
  2. Run buildcharts update to create or refresh Chart.lock.
  3. Run buildcharts generate to pull charts and generate the build plan.
  4. Run docker buildx bake --file .buildcharts/docker-bake.hcl.

​
Why use it

  • Infrastructure as code for builds. Helm charts package and version Kubernetes deployment configuration. BuildCharts brings that model to build pipelines, treating them as platform-owned, versioned artifacts.
  • Narrow responsibility. BuildCharts is a thin generation and orchestration layer that standardizes builds without trying to own scheduling, secrets, artifact hosting, deployments, or runtime operations. The rest of the delivery stack stays where it already is.
  • Low lock-in. No proprietary execution runtime is introduced. Build intent stays in the repository, reusable implementation stays in versioned OCI-hosted charts, and the generated output remains a standard Docker Buildx Bake plan. CI providers, build infrastructure, or registry hosting can change without replacing the overall model.
  • Reuse of standard technology. OCI registries, Dockerfiles, BuildKit, and Docker Buildx Bake remain in place. The value comes from standardizing how those pieces are connected, not from replacing them with a custom backend.
  • Isolated build tooling. Build, test, and scanning tools can run inside Docker build stages instead of being installed directly on CI runners. For example, image scanners such as Trivy can run as part of the containerized build flow, keeping tool dependencies versioned and limiting the host-side surface area for supply-chain risk.
  • Simple fallback. The generated Docker Buildx Bake plan is concrete and inspectable. It can be debugged locally, executed directly with docker buildx bake, or even committed when teams want to reduce generator dependency in exchange for a less dynamic chart update flow.

​
What BuildCharts optimizes for

Shared build logic

Centralize shared build logic in versioned OCI charts while keeping repository-local configuration focused on build intent.

Shared governance

Centralize governance in shared chart implementations, including Dockerfile linting, security scanning, policy checks, and compliance controls, instead of re-creating them per repository.

Lightweight repo config

Keep repository configuration lightweight and developer-friendly by expressing build intent in build.yml while chart implementations define how it runs.

Local and CI parity

Run the same generated Docker Buildx Bake plan on a developer machine and in CI to make failures easier to reproduce and troubleshoot.

Provider-agnostic execution

Stay provider-agnostic by generating Docker-native build plans instead of embedding build logic in provider-specific pipeline steps.

Dependency-based rollout

Treat shared build logic as a dependency: follow chart tags such as latest, 8.0, or 8.0.x for semantic-version-based rollout, or use Chart.lock to pin resolved digests for a more controlled and repeatable model.

Controlled rollout

Reduce drift and blast radius by reviewing and versioning chart changes centrally before individual services adopt them.

Extensibility

Extend the model with built-in plugins and custom charts for organization-specific build requirements.

​
Next steps

Install

Get up and running

Building charts

How to build your own charts

CLI

Explore commands and usages

Plugins

Extend builds using custom plugins
Last modified on May 4, 2026