Considerations

Documentation Index

Fetch the complete documentation index at: https://buildcharts.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Container registry runtime dependency

BuildCharts pulls charts from an OCI-compliant container registry during buildcharts update and buildcharts generate. That makes the registry a runtime dependency for generation:

• Builds depend on registry uptime and authentication.
• Registry outages or auth misconfiguration can block generation.

BuildCharts partially mitigates this with a local blob cache. Charts are cached by digest under the temp directory (<temp>/buildcharts/oci/blobs). If the digest already exists in that cache, the cached chart blob is reused instead of downloaded again. Caching improves performance and reduces registry traffic, but registry access is still required to resolve digests and validate lock files. For ephemeral CI runners, consider persisting the blob cache between runs.

​

Docker toolchain dependency

BuildCharts generates a plan that runs through Docker Buildx/BuildKit. Changes in Docker tooling, builder configuration, or security posture can affect all builds that rely on it. At scale, standardize the Docker/Buildx/BuildKit versions used in CI and on remote builders. The Dockerfile frontend syntax version can also be pinned in chart Dockerfiles to reduce surprises from Dockerfile parsing changes. For example, a # syntax=docker/dockerfile:1.1 directive as the first line pins the Dockerfile syntax frontend. See Dockerfile syntax directive.

​

Generator dependency and fallbacks

BuildCharts is a generator. If generation is blocked, builds are blocked. As a fallback, teams can check in the generated docker-bake.hcl together with the Dockerfiles. This keeps the generated build artifacts versioned in the repository instead of generating them during CI runs. That fallback comes with trade-offs:

• Artifact churn. Chart updates require regenerating/committing generated artifacts.
• Drifting. Repositories can fall behind upstream chart fixes and improvements.

​

Parallelism trade-offs

Bake can execute many targets in parallel. On large repositories and shared runners, this can saturate CPU, I/O, and cache storage. If parallel execution overwhelms a runner, BuildKit solver concurrency can be limited with max-parallelism in buildkitd.toml. See Docker BuildKit resource limiting. This can reduce contention and make builds more predictable, but it also lowers peak throughput, so it works best when tuned alongside cache strategy rather than treated as a universal fix.

​

Caching trade-offs

Cache strategy should be treated as part of build design. Docker build cache lets BuildKit reuse previous build results instead of rebuilding every layer on every run. See Docker build cache. In practice, good cache reuse can reduce build time and registry traffic, while poor cache design can add complexity without delivering the speed benefit. This matters more on ephemeral CI runners, where the local builder cache disappears between jobs. In that case, external cache backends can help preserve useful cache state across runs. Docker documents several cache backends, including inline, registry, local, and gha, plus provider-specific backends such as s3 for AWS S3 and azblob for Azure Blob Storage. See Docker cache storage backends. The selected backend should match the platform and access model, and extra cache import/export steps also add I/O, storage cost, and troubleshooting surface area.

​

Template indirection and troubleshooting

Chart indirection helps reuse stages, but it can also obscure root causes when builds fail. Plan for troubleshooting workflows that inspect generated artifacts and execution output. See Docker builds and Troubleshooting.

​

Secrets and credentials

BuildCharts does not manage secrets. Credentials still need to be provisioned, and their flow into builds still needs to be defined. Plugins can help write local config files and environment variables for common ecosystems, but ownership of secret lifecycle, auditability, and access control stays with the CI/platform setup. See Plugins.

​

Run from your own ecosystem (optional)

Reducing supply-chain risk (for example vendor compromise or mutable upstream artifacts) may justify forking and operating BuildCharts within an internal ecosystem:

• Publish dotnet-buildcharts tool package to an internal NuGet feed, and restore it from there in CI.
• Use Chart lock files to pin chart digests and make builds deterministic.
• Apply chart governance and validation (review policies, chart signing, Dockerfile scanning). See Trust and integrity.