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

# Lock files

> Repeatable chart resolution and controlled updates.

`buildcharts update` creates a lock file with pinned chart dependencies.

## How lock files work

BuildCharts can pin chart dependencies from `charts/buildcharts/Chart.yaml` in `charts/buildcharts/Chart.lock`.

The purpose of the lock file is to make chart resolution more repeatable across local runs and CI. Instead of always following the current state of a chart tag in the registry, BuildCharts can pin the exact resolved digest for each dependency. That reduces drift from upstream chart changes and lets teams adopt chart updates intentionally instead of picking them up implicitly.

This is also how you avoid the mutable tag problem when you want immutability. A tag such as `0.0.1` or `latest` can be moved or republished in the registry, but the digest recorded in `Chart.lock` points to one exact artifact. If the tag later has changed, BuildCharts detects the mismatch instead of silently consuming changed chart content.

## Update strategies

BuildCharts works with or without `charts/buildcharts/Chart.lock`. That gives you two dependency update models:

<Steps>
  <Step title="With a lock file">
    BuildCharts pins chart digests instead of following mutable registry tags. This is the more controlled model and usually fits best when there is also an automated update workflow around chart versions, for example through [Dependabot](https://github.com/dependabot) or [Renovate](https://github.com/renovatebot/renovate).
  </Step>

  <Step title="Without a lock file">
    BuildCharts follows the chart tags from the registry, such as `latest`, `8.0`, or `8.0.x`, enabling different rollout strategies with semantic versioning.
  </Step>
</Steps>

## Refresh the lock file

Run this to change chart versions or pin current digests:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts update
```

This resolves each `repository/name:version` reference and writes `charts/buildcharts/Chart.lock`.

This is the repeatability layer for chart dependencies. `Chart.yaml` says which chart version you want, while `Chart.lock` records the exact OCI digest that was resolved at that point in time. In practice, that gives you more reproducible builds, clearer dependency state across repositories, and safer upgrades when platform teams publish new chart versions.

**Example**

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
dependencies:
  - name: dotnet-build
    version: 0.0.1
    repository: oci://registry-1.docker.io/buildcharts/dotnet-build
    digest: sha256:...
lockVersion: 1
```

## Validation rules

When `charts/buildcharts/Chart.lock` exists and you do not pass `--ignore-lock`, `buildcharts generate` checks:

* Every dependency in `Chart.yaml` has a matching lock entry
* The locked version still matches `Chart.yaml`
* The lock file does not contain orphaned dependencies
* The registry digest still matches the locked digest during chart pull

If any of those checks fail, generation stops and tells you to run `buildcharts update`.

If `Chart.lock` does not exist, `generate` still works. It pulls the current tags from the registry and skips lock validation.

### Skip lock validation when needed

This skips lock enforcement during generation:

```bash theme={"theme":{"light":"plastic","dark":"plastic"}}
buildcharts generate --ignore-lock
```

## Related pages

* [Charts](/core-features/charts)