fix: properly skip docker builds of skipped builds (#4747)

refs https://github.com/orgs/goreleaser/discussions/4469 closes
https://github.com/goreleaser/goreleaser/issues/4746

Also made the error better, and added more details to the docs.

internal/pipe/docker/docker.go

@@ -142,6 +142,9 @@ func (Pipe) Run(ctx *context.Context) error {
 				filters = append(filters, artifact.ByIDs(docker.IDs...))
 			}
 			artifacts := ctx.Artifacts.Filter(artifact.And(filters...))
+			if d := len(docker.IDs); d > 0 && len(artifacts.GroupByID()) != d {
+				return pipe.Skipf("expected to find %d artifacts for ids %v, found %d\nLearn more at https://goreleaser.com/errors/docker-build\n", d, docker.IDs, len(artifacts.List()))
+			}
 			log.WithField("artifacts", artifacts.Paths()).Debug("found artifacts")
 			return process(ctx, docker, artifacts.List())
 		})

www/docs/customization/docker.md

@@ -68,6 +68,12 @@ dockers:
     goamd64: "v2"
 
     # IDs to filter the binaries/packages.
+    #
+    # Make sure to only include the IDs of binaries you want to `COPY` in your
+    # Dockerfile.
+    #
+    # If you include IDs that don't exist or are not available for the current
+    # architecture being built, the build of the image will be skipped.
     ids:
       - mybuild
       - mynfpm

www/docs/errors/docker-build.md

@@ -17,6 +17,14 @@ its root, so you can just `COPY binaryname /bin/binaryname` and etc.
 
 Below you can find some **don'ts** as well as what you should **do**.
 
+## `expected to find X artifacts for ids [id1 id2], found Y`
+
+The `ids` property in the Dockers configuration tells GoReleaser which build IDs
+to include.
+You need to remove IDs that don't exist and/or don't build for the architecture
+of the image being built.
+Leaving it empty is also fine if you don't need any binaries.
+
 ## `use docker --context=default buildx to switch to context "default"`
 
 The "default" context is a built-in context in "docker buildx", and it is automatically created. This context typically points to the local Docker environment and is used by default for building images. It has to be active for `goreleaser` to build images with "buildx".