Add subject to attestation manifests

[crazy-max]

relates to docker/build-push-action#1260

subject has been added to the OCI spec 1.1.0: https://specs.opencontainers.org/image-spec/manifest/?v=v1.1.0#image-manifest-property-descriptions. This property specifies a descriptor of another manifest.

Some registry providers like GAR use this property to link back to the original manifest. I think it would be fine to have this property attached to attestation manifests.

cc @wieringen @dvdksn @tianon

[tonistiigi]

Can we do some cross-registry testing to understand what(if) common registries would return errors when pushing a manifest with subject. Otherwise we can add an opt-in for it.

[crazy-max]

Can we do some cross-registry testing to understand what(if) common registries would return errors when pushing a manifest with subject. Otherwise we can add an opt-in for it.

Yes I can look to have this in our e2e tests on build-push-action repo: https://github.com/docker/build-push-action/blob/master/.github/workflows/e2e.yml

[crazy-max]

Tested here: https://github.com/docker/build-push-action/actions/runs/12182820627

Seems only Gitlab fails: https://github.com/docker/build-push-action/actions/runs/12182820627/job/33982750597#step:13:11

Exists    d9014c462484 hi.txt
Error response from registry: manifest blob unknown: blob unknown to registry: sha256:9b962b6abadee78b1d83d3b58a879fcbf0d66ea6d34c934ef3285301f3860b22
Error: Process completed with exit code 1.

Tested also locally:

FROM alpine
RUN echo hello

$ docker buildx --builder builder build -t crazymax/buildkit-5561:multi --platform linux/amd64,linux/arm64 --push .
...
#10 exporting to image
#10 exporting layers done
#10 exporting manifest sha256:d3f28426b6941bb3d874b09d95019f4316284732cb5c8688b57d8159a28e0836 done
#10 exporting config sha256:4891e75c3b5e9ab03dbe24176ed3a580933fca9b47b44e2ad29338dd62cd05cd done
#10 exporting attestation manifest sha256:9b2bd7af0c3b6af640cea9cbd0998ade17afa04485810fa4720e40d466a68c8f
#10 exporting attestation manifest sha256:9b2bd7af0c3b6af640cea9cbd0998ade17afa04485810fa4720e40d466a68c8f 0.0s done
#10 exporting manifest sha256:9985f0b4525d4369e8f702daa8b96016cf62b94f07f0897b54a12c08565c2008 done
#10 exporting config sha256:dbaccb48e93c0be06f4e55ddab642cf7f8ff678f5f7c61209839ddbee07b099e done
#10 exporting attestation manifest sha256:04c144745d07d8a41a292144c9239c76f71f3487d121100797fb6c023c6d1826 0.0s done
#10 exporting manifest list sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf 0.0s done
#10 pushing layers
#10 ...

#11 [auth] crazymax/buildkit-5561:pull,push token for registry-1.docker.io
#11 DONE 0.0s

#10 exporting to image
#10 pushing layers 1.6s done
#10 pushing manifest for docker.io/crazymax/buildkit-5561:multi@sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf
#10 pushing manifest for docker.io/crazymax/buildkit-5561:multi@sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf 1.5s done
#10 DONE 3.3s

See https://explore.ggcr.dev/?image=crazymax/buildkit-5561:multi@sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf

{
   "schemaVersion":2,
   "mediaType":"application/vnd.oci.image.index.v1+json",
   "manifests":[
      {
         "mediaType":"application/vnd.oci.image.manifest.v1+json",
         "size":667,
         "digest":"sha256:d3f28426b6941bb3d874b09d95019f4316284732cb5c8688b57d8159a28e0836",
         "platform":{
            "architecture":"amd64",
            "os":"linux"
         }
      },
      {
         "mediaType":"application/vnd.oci.image.manifest.v1+json",
         "size":667,
         "digest":"sha256:9985f0b4525d4369e8f702daa8b96016cf62b94f07f0897b54a12c08565c2008",
         "platform":{
            "architecture":"arm64",
            "os":"linux"
         }
      },
      {
         "mediaType":"application/vnd.oci.image.manifest.v1+json",
         "size":566,
         "digest":"sha256:9b2bd7af0c3b6af640cea9cbd0998ade17afa04485810fa4720e40d466a68c8f",
         "platform":{
            "architecture":"unknown",
            "os":"unknown"
         },
         "annotations":{
            "vnd.docker.reference.digest":"sha256:d3f28426b6941bb3d874b09d95019f4316284732cb5c8688b57d8159a28e0836",
            "vnd.docker.reference.type":"attestation-manifest"
         }
      },
      {
         "mediaType":"application/vnd.oci.image.manifest.v1+json",
         "size":566,
         "digest":"sha256:04c144745d07d8a41a292144c9239c76f71f3487d121100797fb6c023c6d1826",
         "platform":{
            "architecture":"unknown",
            "os":"unknown"
         },
         "annotations":{
            "vnd.docker.reference.digest":"sha256:9985f0b4525d4369e8f702daa8b96016cf62b94f07f0897b54a12c08565c2008",
            "vnd.docker.reference.type":"attestation-manifest"
         }
      }
   ]
}

Then attach an artifact with oras:

$ echo "Hello, world!" > hi.txt
$ oras attach --artifact-type doc/example docker.io/crazymax/buildkit-5561:multi@sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf hi.txt
✓ Exists    application/vnd.oci.empty.v1+json                                                                                                                                                         2/2  B 100.00%     0s
  └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
✓ Exists    hi.txt                                                                                                                                                                                  14/14  B 100.00%     0s
  └─ sha256:d9014c4624844aa5bac314773d6b689ad467fa4e1d1a50a1b8a99d5a95f72ff5
✓ Uploaded  application/vnd.oci.image.manifest.v1+json                                                                                                                                            722/722  B 100.00%  632ms
  └─ sha256:712d3058686fa85a19077108e8a74affc44eee2c858144080f64b65e871fb57a
Attached to [registry] docker.io/crazymax/buildkit-5561:multi@sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf
Digest: sha256:712d3058686fa85a19077108e8a74affc44eee2c858144080f64b65e871fb57a

See "attached" manifest with subject attribute: https://explore.ggcr.dev/?image=crazymax%2Fbuildkit-5561%3Amulti%40sha256%3A712d3058686fa85a19077108e8a74affc44eee2c858144080f64b65e871fb57a

{
   "schemaVersion":2,
   "mediaType":"application/vnd.oci.image.manifest.v1+json",
   "artifactType":"doc/example",
   "config":{
      "mediaType":"application/vnd.oci.empty.v1+json",
      "size":2,
      "digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "data":"e30="
   },
   "layers":[
      {
         "mediaType":"application/vnd.oci.image.layer.v1.tar",
         "size":14,
         "digest":"sha256:d9014c4624844aa5bac314773d6b689ad467fa4e1d1a50a1b8a99d5a95f72ff5",
         "annotations":{
            "org.opencontainers.image.title":"hi.txt"
         }
      }
   ],
   "subject":{
      "mediaType":"application/vnd.oci.image.index.v1+json",
      "size":1607,
      "digest":"sha256:166f78ab728dddc7f54a4cf12fdd37f604f4c1f12c521c0b78c29be6588752bf"
   },
   "annotations":{
      "org.opencontainers.image.created":"2024-12-05T15:37:17Z"
   }
}

[crazy-max]

Seems only Gitlab fails: https://github.com/docker/build-push-action/actions/runs/12182820627/job/33982750597#step:13:11

Bug on GitLab? oras-project/oras#1224 (comment)
Allow list strikes again? (cc @sudo-bmitch)

Other run with debug enabled: https://github.com/docker/build-push-action/actions/runs/12183567244/job/33985301861#step:13:1

[sudo-bmitch]

Gitlab is known to not be OCI 1.1 conformant (they only support 1.0). They have an allow list for the config media type and block unknown values.
https://conformance.opencontainers.org/#gitlab-container-registry