Support index-level annotations in `pack manifest annotate`

[ddusht]

Description

pack manifest annotate currently only applies annotations to individual manifests within an index. There is no way to annotate the index (manifest list) itself.

Expected Behavior

Allow adding annotations to the top-level index manifest.

Example:

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:...",
      "annotations": {
        "test": "passed"
      },
      "platform": {
        "architecture": "amd64",
        "os": "linux"
      }
    }
  ],
+  "annotations": {
+    "test": "passed"
+  }
}

Proposed solution

Extend pack manifest annotate to support index-level annotations. Possible approaches:

• Add a flag (e.g. --index or --root) to target the index manifest

Additional context

• This feature should be documented somewhere

[jjbustamante]

@ddusht Thanks for reporting this issue! I wasn't sure if the pack manifest commands were used by the community!. All the pack manifest commands were discussed in this RFC. I remember we tried to keep the same interface as docker or podman CLI, did you check if any of these tools offer similar feature and which flag do they use in such as case?

[Rvk30]

Hi, I'd like to work on this issue! I'm a beginner contributor , could you point me to the relevant files where pack manifest annotate is implemented? Also, should I follow the --index flag approach mentioned in the issue?

[jjbustamante]

Hi, I'd like to work on this issue! I'm a beginner contributor , could you point me to the relevant files where pack manifest annotate is implemented? Also, should I follow the --index flag approach mentioned in the issue?

Hi @Rvk30, happy to assign the issue to you, but wait for us to define the interface.

[jjbustamante]

Looked at how docker and podman expose this, plus what it'll take to implement on our side.

Prior art

• Podman uses an --index flag — same --annotation flag, but --index flips its meaning to apply to the index itself; the <image> positional is omitted. Docs: https://docs.podman.io/en/latest/markdown/podman-manifest-annotate.1.html
• Docker buildx (imagetools create) uses type prefixes inside the value: --annotation "index:key=value". Different shape, and only on imagetools create — docker manifest annotate itself doesn't support index-level annotations.

We'll follow podman with an --index flag. Per RFC 0124, pack manifest * already mirrors podman's interface, and our positional layout (<manifest-list> <manifest>) is identical to podman manifest annotate <list> <image>. Adding --index keeps that alignment. Docker's prefix approach would diverge from how our --annotations flag already parses values.

One thing to copy from podman's experience: podman-container-tools/podman#24750 was a panic when --index was passed with a positional image arg. We should reject that combination explicitly.

Heads up: imgutil work needed first

imgutil's ImageIndex interface today only supports per-entry annotations:

SetAnnotations(digest name.Digest, annotations map[string]string) (err error)

Every call requires a name.Digest — no way to set annotations on the index itself. So this issue splits across two repos:

1. buildpacks/imgutil: add a method to the ImageIndex interface (e.g. SetIndexAnnotations(annotations map[string]string) error), implementation in cnb_index.go, and the test fake in fakes/image_index.go. Needs an imgutil release before pack can consume it.
2. buildpacks/pack (depends on 1): bump the imgutil dep, then implement the --index flag.

Concrete proposal — pack side

Once imgutil support is in:

• Add --index boolean flag to pack manifest annotate in internal/commands/manifest_annotate.go.
• When --index is set:
  • <manifest> positional becomes invalid → return a clear error if provided.
  • --os, --arch, --variant are also invalid (those describe a manifest entry, not an index) → error if passed alongside --index.
  • --annotations is applied to the top-level annotations field via the new imgutil method.
• Update Use: line and add an example to the Long description showing both forms.
• In pkg/client/manifest_annotate.go, extend ManifestAnnotateOptions with an Index bool field and switch on it.

Tests to add:

• internal/commands/manifest_annotate_test.go: --index succeeds; --index + positional <manifest> errors; --index + --os/--arch/--variant errors; existing per-entry behavior still works.
• pkg/client/manifest_annotate_test.go: client-layer coverage for the new path.

@Rvk30 Files on the pack side:

• internal/commands/manifest_annotate.go + _test.go
• pkg/client/manifest_annotate.go + _test.go

Given the imgutil prerequisite, this is bigger than a typical first issue — involves a cross-repo PR and waiting on an imgutil release. Happy to mentor you through it if you want to take it on; otherwise let us know and we can point you at something smaller-scoped. If you do go for it, open a draft PR on buildpacks/imgutil first so we can review the interface shape, and the pack PR can follow.

I'll drop the `good first issue` label given the imgutil dependency.

[Rvk30]

Thanks for the detailed breakdown! I think this is a bit too complex for me right now as a first contribution. Could you point me to something smaller-scoped? I'd really like to start contributing to this repo.

[gunishmatta]

Hey @jjbustamante happy to work on this, can take on imgutil prerequisite change first.

[TIR44]

I opened the imgutil prerequisite PR: buildpacks/imgutil#306.

Current shape:

• adds ImageIndex.SetIndexAnnotations(map[string]string)
• implements it through go-containerregistry's index annotation mutation
• preserves top-level annotations when SaveDir() rewrites the local index.json
• includes unit coverage for OCI and Docker manifest list index annotations, no-annotation saves, and merge/update behavior for existing index annotation keys

Current status:

• ready for review, not draft
• latest commit: 6ad67aa
• GitHub checks passed: DCO, Linux, Linux containerd, Windows, Codecov patch, and Codecov project

Once the imgutil API shape looks good, I can follow up here with the pack-side pack manifest annotate --index implementation described above.