Merge pull request #3882 from mvanhorn/docs/3556-bake-set-ssh-syntax

docs: document inline --set override syntax for ssh and composable attributes

docs/bake-reference.md

@@ -1057,6 +1057,12 @@ RUN --mount=type=ssh \
     && git clone git@github.com:user/my-private-repo.git
 ```
 
+> [!NOTE]
+> When overriding `ssh` from the command line with `--set`, use the inline
+> `id=path` string form rather than the object form shown above, for example
+> `docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519"`. Separate
+> multiple paths with commas. See [`bake --set`][set] for details.
+
 ### `target.tags`
 
 Image names and tags to use for the build target.
@@ -1519,6 +1525,7 @@ target "webapp-dev" {
 [platform]: https://docs.docker.com/reference/cli/docker/buildx/build/#platform
 [run_mount_secret]: https://docs.docker.com/reference/dockerfile/#run---mounttypesecret
 [secret]: https://docs.docker.com/reference/cli/docker/buildx/build/#secret
+[set]: https://docs.docker.com/reference/cli/docker/buildx/bake/#set
 [ssh]: https://docs.docker.com/reference/cli/docker/buildx/build/#ssh
 [tag]: https://docs.docker.com/reference/cli/docker/image/build/#tag
 [target]: https://docs.docker.com/reference/cli/docker/image/build/#target

docs/reference/buildx_bake.md

@@ -495,3 +495,39 @@ You can append using `+=` operator for the following fields:
 
 > [!NOTE]
 > ¹ These fields already append by default.
+
+#### Inline values for composable attributes
+
+Some fields, such as `ssh`, `secret`, `output`, `cache-to`, `cache-from`,
+`attest`, and `annotations`, are composable attributes that accept a list of
+object values in a Bake file. When you override these fields with `--set`, you
+provide each value using the same inline string syntax as the corresponding
+build flag, not the HCL object form. The `--set` override replaces or appends
+to the list as a whole; it doesn't address individual sub-fields with a
+sub-selector. Only the map-valued fields `args`, `contexts`, `labels`, and
+`extra-hosts` support targeting a specific entry with a sub-key (for example
+`--set target.args.MYARG=value`).
+
+For example, to set the SSH agent socket or key for a target, use the same
+`id=path` form accepted by [`build --ssh`](buildx_build.md#ssh):
+
+```console
+$ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519"
+```
+
+To expose multiple paths for the same `id`, separate them with commas in the
+second part:
+
+```console
+$ docker buildx bake --set "*.ssh=default=$HOME/.ssh/id_ed25519,$HOME/.ssh/id_rsa"
+```
+
+Your shell expands `$HOME` before buildx sees the value. The equivalent Bake
+file definition uses the
+[`homedir`](https://docs.docker.com/build/bake/stdlib/#homedir) HCL function:
+
+```hcl
+target "default" {
+  ssh = [{ id = "default", paths = ["${homedir()}/.ssh/id_ed25519", "${homedir()}/.ssh/id_rsa"] }]
+}
+```