docker_compose_yaml

load("@rules_docker_compose//docker_compose:docker_compose_yaml.bzl", "docker_compose_yaml")

docker_compose_yaml(name, data, out, config, images, interpolate, interpolation_env, yamls)

Merges docker-compose configurations and validates image references.

This rule uses docker-compose config to merge one or more docker-compose YAML files (and/or an inline Starlark configuration) into a single, canonical configuration. It also validates that all images referenced in the configuration have corresponding loader targets specified in the images attribute.

At least one of yamls or config must be provided. When both are given, they are merged together using docker-compose config (the config JSON is applied on top of the YAML files).

The merged YAML preserves the original image tags declared in your inputs — it is diff-reviewable and safe to share outside Bazel (e.g. check it into version control, hand off to a teammate's docker compose -f invocation, etc.).

For each image with a registered loader, the merger ALSO computes a content digest (sha256(index.json) for rules_oci, sha256(manifest_file) for rules_img) and emits a second YAML where services.*.image references are rewritten to a content-derived unique tag of the form <repo>:rdc-<digest12>. That rewritten YAML is consumed only by docker_compose_test to isolate parallel test runs on a shared engine. docker_compose_binary (and the default output of this rule) use the original tags.

Supported image loader types:

Loader	Source
oci_load	rules_oci
image_load	rules_img

Example with YAML files:

load("@rules_docker_compose//docker_compose:docker_compose_yaml.bzl", "docker_compose_yaml")
load("@rules_oci//oci:defs.bzl", "oci_load")

oci_load(
    name = "my_image.load",
    image = ":my_image",
    repo_tags = ["my-app:latest"],
)

docker_compose_yaml(
    name = "compose",
    yamls = ["docker-compose.yaml"],
    images = [":my_image.load"],
)

Example with inline Starlark config:

load("@rules_docker_compose//docker_compose:docker_compose_config.bzl", "docker_compose_config")
load("@rules_docker_compose//docker_compose:docker_compose_yaml.bzl", "docker_compose_yaml")
load("@rules_oci//oci:defs.bzl", "oci_load")

oci_load(
    name = "nginx.load",
    image = ":nginx",
    repo_tags = ["my-app/nginx:latest"],
)

docker_compose_yaml(
    name = "compose",
    config = docker_compose_config(
        services = {
            "web": {
                "image": "my-app/nginx:latest",
                "ports": ["8080:80"],
            },
        },
    ),
    images = [":nginx.load"],
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	Additional files referenced by the docker-compose configuration (e.g. env_file, config files, secret files, bind-mount sources). These are made available during the merge action and propagated to consuming rules for runtime availability.	List of labels	optional	`[]`
out	Optional output filename for the merged docker-compose YAML. Defaults to `{name}/docker-compose.yaml`.	Label; nonconfigurable	optional	`None`
config	A JSON-encoded docker-compose configuration string. Use `docker_compose_config()` to produce this value from structured Starlark dicts. Can be used alone or combined with `yamls`.	String	optional	`""`
images	Image loader targets that provide the container images referenced in the configuration. Each image referenced in the docker-compose config must have a corresponding loader target. See the rule documentation for supported loader types.	List of labels	optional	`[]`
interpolate	Whether to resolve `${VAR}` references when merging. When `True` (the default), `docker-compose config` interpolates every variable at build time. Bazel actions run with a sanitized environment, so a variable that isn't declared in `interpolation_env` resolves to an empty string. Set to `False` to keep `${VAR}` references verbatim in the merged YAML so docker-compose resolves them at runtime instead — the right choice for per-developer or per-machine values like `${USER}`. `services.*.image` is always resolved at build time regardless, because each image reference must be matched to a loader target; declare any variables it uses in `interpolation_env`.	Boolean	optional	`True`
interpolation_env	Environment variables used to interpolate the compose files at build time. These are visible only to the merge action, not to the containers. Because the values are declared in the BUILD file rather than read from the invoking shell, they keep the merged YAML hermetic and correctly cached. When `interpolate = False` this applies to `services.*.image` only, since that is the only field still resolved at build time; every other reference is left for docker-compose to resolve at runtime. To set variables the containers see at runtime, use the compose file's own `environment`/`env_file` keys. To let a variable come from the host at runtime, set `interpolate = False` and (for `bazel test`) list it in the `env_inherit` attribute of `docker_compose_test`.	Dictionary: String -> String	optional	`{}`
yamls	One or more docker-compose YAML files to merge. Files are merged in order using `docker-compose config`. At least one of `yamls` or `config` must be provided.	List of labels	optional	`[]`

rules_docker_compose

docker_compose_yaml

Rules

docker_compose_yaml