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

# Metadata

> Repository metadata for build generation.

Use `build.yml` to describe what your repository should build. The generator reads this file from the repository root.

## Schema

Use the shipped schema for editor validation:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
# yaml-language-server: $schema=https://raw.githubusercontent.com/buildcharts/buildcharts/main/schemas/v1beta.json
```

## Top-level fields

### `version`

String value for the config version. The repository samples use `v1beta`.

### `variables`

Variables become Bake variables and are also exposed through the generated `_common` target args.

Supported forms:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
variables:
  - VERSION
  - COMMIT
```

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
variables:
  - VERSION: "1.0.0-local"
  - COMMIT: ""
```

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
variables:
  - VERSION:
      default: "1.0.0-local"
  - COMMIT: ""
```

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
variables:
  VERSION: "1.0.0-local"
  COMMIT: ""
```

### `plugins`

Optional list of plugin names:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
plugins:
  - NuGetAuthenticate@v1
  - TestcontainersDinD@v1
```

### `targets`

Required mapping of source path to one or more target definitions.

You must define exactly one `build` target across the whole file.

Supported forms:

Single scalar:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  buildcharts.sln: build
```

Mapping with one type:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  src/App/App.csproj:
    type: docker
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/runtime:10.0
      tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]
```

Mapping with multiple types that share the same `with` block:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  src/App/App.csproj:
    type: [build, test]
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0
```

Sequence of entries:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  src/App/App.csproj:
    - type: build
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0

    - type: docker
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/runtime:10.0
        tags: ["docker.io/example/app:${VERSION}-${COMMIT}"]
```

### `types`

Optional type-level contexts and matrix expansion.

Use `types.<type>.contexts` when every generated target of the same type should receive the same Docker Bake named context:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
types:
  nuget:
    contexts:
      git: .git
```

Use `types.<type>.matrix` when you want to expand every target of a given type across one or more axes:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
types:
  docker:
    matrix:
      platform: ["linux/amd64", "linux/arm64"]
```

Every target of that type is expanded across the matrix axes. Each axis value is exposed to the chart as an uppercase snake case build arg.

For example, this metadata:

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
targets:
  src/dotnet-krp/dotnet-krp.csproj:
    - type: publish

types:
  publish:
    matrix:
      runtime: ["win-x64", "win-arm64"]
```

produces one generated Bake target per matrix value. In the generated `docker-bake.hcl`, the `publish` target becomes a Bake matrix with:

* One `item` entry for the source target
* One `runtime` axis with both values
* A target name pattern such as `${item.name}_${runtime}`
* An injected build arg `RUNTIME="${runtime}"`

That means a single `type: publish` definition expands into two generated publish variants, one for `win-x64` and one for `win-arm64`.

## Target keys

### `with`

Each target can define these supported options under `with`.

| Key          | Effect                                            |
| ------------ | ------------------------------------------------- |
| `contexts`   | Adds Docker Bake named contexts                   |
| `tags`       | Sets Bake tags for the generated target           |
| `dockerfile` | Overrides the default chart Dockerfile path       |
| `allow`      | Sets BuildKit entitlements such as `network.host` |
| `args`       | Adds per-target build args                        |

Notes:

* `contexts` is a mapping of HCL identifier names to non-empty context values.
* Use `docker-image://...` when a chart Dockerfile expects a named image context such as `base`.
* The context name `build` is reserved. BuildCharts automatically wires non-`build` targets to `target:build`.
* `args` values can be strings or arrays
* Array values are emitted as comma-separated strings in the generated HCL
* If you omit `dockerfile`, BuildCharts uses `./.buildcharts/<chart-name>/Dockerfile`

## Alias resolution

Each target `type` must match an alias in `charts/buildcharts/Chart.yaml`. If you define `type: publish`, you also need a chart dependency whose `alias` is `publish`.

## Example

```yaml theme={"theme":{"light":"plastic","dark":"plastic"}}
# yaml-language-server: $schema=https://raw.githubusercontent.com/eddietisma/buildcharts/main/schemas/v1beta.json

version: v1beta

variables:
  VERSION: "1.0.0"
  COMMIT: "local"

targets:
  buildcharts.sln:
    type: build
    with:
      contexts:
        base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0

  src/BuildCharts.Tool/BuildCharts.Tool.csproj:
    - type: nuget
    - type: docker
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/runtime:10.0
        tags: ["docker.io/buildcharts/buildcharts:${VERSION}-${COMMIT}"]

  test/BuildCharts.Tests/BuildCharts.Tests.csproj:
    type: test

types:
  nuget:
    contexts:
      git: .git
```