> ## Documentation Index
> Fetch the complete documentation index at: https://buildcharts.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

> Generate pipelines using declarative metadata and OCI-hosted build charts.

## 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](https://docs.docker.com/reference/cli/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.

<Note>
  If you already know [Helm](https://helm.sh), 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.
</Note>

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

<Note>
  For a deeper architectural discussion of the problem space, goals, trade-offs, and governance model, read the [Assessment and Rationale](https://github.com/buildcharts/buildcharts/blob/main/docs/assessment.md) on GitHub.
</Note>

## Workflow

```text theme={"theme":{"light":"plastic","dark":"plastic"}}
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](https://trivy.dev/latest/) 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

<CardGroup cols={2}>
  <Card title="Shared build logic" icon="layer-group">
    Centralize shared build logic in versioned OCI charts while keeping repository-local configuration focused on build intent.
  </Card>

  <Card title="Shared governance" icon="shield">
    Centralize governance in shared chart implementations, including Dockerfile linting, security scanning, policy checks, and compliance controls, instead of re-creating them per repository.
  </Card>

  <Card title="Lightweight repo config" icon="file-lines">
    Keep repository configuration lightweight and developer-friendly by expressing build intent in `build.yml` while chart implementations define how it runs.
  </Card>

  <Card title="Local and CI parity" icon="laptop-code">
    Run the same generated Docker Buildx Bake plan on a developer machine and in CI to make failures easier to reproduce and troubleshoot.
  </Card>

  <Card title="Provider-agnostic execution" icon="arrows-left-right">
    Stay provider-agnostic by generating Docker-native build plans instead of embedding build logic in provider-specific pipeline steps.
  </Card>

  <Card title="Dependency-based rollout" icon="code-branch">
    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.
  </Card>

  <Card title="Controlled rollout" icon="shield-halved">
    Reduce drift and blast radius by reviewing and versioning chart changes centrally before individual services adopt them.
  </Card>

  <Card title="Extensibility" icon="plug">
    Extend the model with built-in plugins and custom charts for organization-specific build requirements.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Install" icon="download" href="/install">
    Get up and running
  </Card>

  <Card title="Building charts" icon="book" href="/charts/define-build-stages">
    How to build your own charts
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="CLI" icon="terminal" href="/cli">
    Explore commands and usages
  </Card>

  <Card title="Plugins" icon="plug" href="/core-features/plugins">
    Extend builds using custom plugins
  </Card>
</CardGroup>