Handle dependencies

Use contexts when a chart Dockerfile needs content from another generated target, a base image, or a local path. This lets stages depend on each other without merging their chart Dockerfiles.

Use additional contexts

A context maps a name to an input:

Input type	Value example
Generated Bake target	`target:<name>`
Docker image	`docker-image://alpine:3.20`
Local path	`.git`
Git URL	`https://github.com/org/repo.git`
HTTP URL	`https://example.com/context.tar`

Read more in the Docker Bake contexts documentation.

Use the default build context

For every generated target except build, BuildCharts adds a context named build that points to the generated build target:

contexts = {
  build = "target:build"
}

Chart Dockerfiles can use build as an upstream stage:

FROM build AS pre-docker

This works because target:build refers to the generated Bake target named build. BuildCharts requires exactly one build target in build.yml, so the context is stable and unambiguous. Keep build for this automatic context. Do not define build under with.contexts or types.<type>.contexts.

Add a target dependency

Use with.contexts when one target needs a named dependency that other targets do not.

targets:
  src/App/App.csproj:
    - type: build
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0
    - type: publish
    - type: docker
      with:
        contexts:
          publish: target:publish
        tags: ["docker.io/example/app:local"]

The generated docker target receives:

The automatic build = "target:build" context
The configured publish = "target:publish" context

Use the configured context in the chart Dockerfile like any named stage:

FROM publish AS published-app

FROM base AS docker
COPY --from=published-app /output /app

Use types.<type>.contexts when every target of a type needs the same dependency.

targets:
  src/App/App.csproj:
    - type: build
      with:
        contexts:
          base: docker-image://mcr.microsoft.com/dotnet/sdk:10.0
    - type: publish
    - type: docker
      with:
        tags: ["docker.io/example/app:local"]

types:
  docker:
    contexts:
      publish: target:publish

This keeps repeated context wiring out of each target definition.

Use image and local contexts

Contexts can also point to images or local paths.

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

  src/Library/Library.csproj:
    type: nuget

types:
  nuget:
    contexts:
      git: .git

A docker chart can consume the base image context:

FROM base AS runtime

A nuget chart can copy from the git local context:

COPY --from=git HEAD /.git/HEAD

For commands that need the full .git directory, bind mount it for the duration of the RUN step:

RUN --mount=type=bind,from=git,source=.,target=/src/.git,readonly \
    git -C /src rev-parse HEAD

Context naming rules

Use context names that are valid HCL identifiers:

Start with a letter or _
Contain only letters, numbers, and _
Use non-empty values

Keep each context name unique per generated target. Do not define the same context name in both with.contexts and types.<type>.contexts.

Overview

Core features

Charts

Quickstart

Plugins

Troubleshooting

Use additional contexts

Use the default build context

Add a target dependency

Use image and local contexts

Context naming rules

​Use additional contexts

​Use the default build context

​Add a target dependency

​Share a dependency by type

​Use image and local contexts

​Context naming rules

Use additional contexts

Use the default build context

Add a target dependency

Share a dependency by type

Use image and local contexts

Context naming rules