Skip to content

imagetools: improve annotation handling - #4091

Open
crazy-max wants to merge 2 commits into
docker:masterfrom
crazy-max:fix-imagetools-annotation-errors
Open

crazy-max wants to merge 2 commits into
docker:masterfrom
crazy-max:fix-imagetools-annotation-errors

Conversation

@crazy-max

Copy link
Copy Markdown
Member

fixes #2148

Untyped imagetools create annotations now target the image index, while manifest annotations return an actionable error because the command doesn't rewrite manifests. Annotations targeting Docker manifest lists now fail instead of being silently discarded, and the error explains how to produce compatible sources with oci-mediatypes=true.

@crazy-max crazy-max added this to the v0.38.0 milestone Sep 17, 2026
@crazy-max
crazy-max marked this pull request as ready for review September 17, 2026 16:03
@crazy-max crazy-max modified the milestones: v0.38.0, v0.39.0 Sep 30, 2026
> It doesn't support annotating manifests or OCI layouts. Annotations also
> require the output to use the OCI image index media type; they aren't
> supported when the sources produce a Docker manifest list. When building
> source images with Buildx, use the `oci-mediatypes=true` output option to

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you remind me, does buildx produce oci mediatypes by default now? I seem to remember there was some heuristic which determined whether an image would be created as oci or docker, and that in most cases a build would produce an OCI index unless you explicitly opt out of provenance etc. But my memory on this is very vague.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's right. Before BuildKit v0.31, exports without attestations used Docker media types, while exports with attestations used OCI media types. Since Buildx enables minimal provenance by default for registry outputs, most Buildx builds already produced an OCI index unless provenance was disabled.

BuildKit v0.31 changed the default to OCI media types regardless. I've updated this note so oci-mediatypes=true is presented as an explicit opt-in for older builders, rather than something current Buildx users generally need.

Relevant upstream change: moby/buildkit#6824

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>
Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>
@crazy-max
crazy-max force-pushed the fix-imagetools-annotation-errors branch from a5967cb to 7816c52 Compare October 16, 2026 12:55

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

imagetools: cryptic error messages for annotation flag

2 participants