[Improvement] Document how to add a description to a multi-arch image (#33759)

Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com>

content/actions/publishing-packages/publishing-docker-images.md

@@ -47,7 +47,7 @@ This guide assumes that you have a complete definition for a Docker image stored
 
 {% ifversion fpt or ghec or ghes > 3.4 %}
 
-{% data reusables.package_registry.about-docker-labels %} For more information, see "[Working with the {% data variables.product.prodname_container_registry %}](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#labelling-container-images)."
+{% data reusables.package_registry.about-annotation-keys %} For more information, see "[Working with the {% data variables.product.prodname_container_registry %}](/packages/working-with-a-github-packages-registry/working-with-the-container-registry#labelling-container-images)."
 
 {% endif %}
 

content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md

@@ -139,17 +139,21 @@ This example builds the `hello_docker` image:
 
 ## Labelling container images
 
-{% data reusables.package_registry.about-docker-labels %} For more information on Docker labels, see [LABEL](https://docs.docker.com/engine/reference/builder/#label) in the official Docker documentation and [Pre-Defined Annotation Keys](https://github.com/opencontainers/image-spec/blob/master/annotations.md#pre-defined-annotation-keys) in the `opencontainers/image-spec` repository.
+{% data reusables.package_registry.about-annotation-keys %} Values for supported keys will appear on the package page for the image.
 
-The following labels are supported in the {% data variables.product.prodname_container_registry %}. Supported labels will appear on the package page for the image.
+For most images, you can use Docker labels to add the annotation keys to an image. For more information, see [LABEL](https://docs.docker.com/engine/reference/builder/#label) in the official Docker documentation and [Pre-Defined Annotation Keys](https://github.com/opencontainers/image-spec/blob/master/annotations.md#pre-defined-annotation-keys) in the `opencontainers/image-spec` repository.
 
-Label | Description
+For multi-arch images, you can add a description to the image by adding the appropriate annotation key to the `annotations` field in the image's manifest. For more information, see "[Adding a description to multi-arch images](#adding-a-description-to-multi-arch-images)."
+
+The following annotation keys are supported in the {% data variables.product.prodname_container_registry %}.
+
+Key | Description
 ------|------------
 | `org.opencontainers.image.source` | The URL of the repository associated with the package. For more information, see "[Connecting a repository to a package](/packages/learn-github-packages/connecting-a-repository-to-a-package#connecting-a-repository-to-a-container-image-using-the-command-line)."
 | `org.opencontainers.image.description` | A text-only description limited to 512 characters. This description will appear on the package page, below the name of the package.
 | `org.opencontainers.image.licenses` | An SPDX license identifier such as "MIT," limited to 256 characters. The license will appear on the package page, in the "Details" sidebar. For more information, see [SPDX License List](https://spdx.org/licenses/).
 
-To add labels to an image, we recommend using the `LABEL` instruction in your `Dockerfile`. For example, if you're the user `monalisa` and you own `my-repo`, and your image is distributed under the terms of the MIT license, you would add the following lines to your `Dockerfile`:
+To add a key as a Docker label, we recommend using the `LABEL` instruction in your `Dockerfile`. For example, if you're the user `monalisa` and you own `my-repo`, and your image is distributed under the terms of the MIT license, you would add the following lines to your `Dockerfile`:
 
 ```dockerfile
 LABEL org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/monalisa/my-repo
@@ -164,3 +168,33 @@ $ docker build \
  --label "org.opencontainers.image.source=https://{% ifversion fpt or ghec %}github.com{% else %}HOSTNAME{% endif %}/monalisa/my-repo" \
  --label "org.opencontainers.image.description=My container image" \
  --label "org.opencontainers.image.licenses=MIT"
+```
+
+### Adding a description to multi-arch images
+
+A multi-arch image is an image that supports multiple architectures. It works by referencing a list of images, each supporting a different architecture, within a single manifest.
+
+The description that appears on the package page for a multi-arch image is obtained from the `annotations` field in the image's manifest. Like Docker labels, annotations provide a way to associate metadata with an image, and support pre-defined annotation keys. For more information, see [Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) in the `opencontainers/image-spec` repository.
+
+To provide a description for a multi-arch image, set a value for the `org.opencontainers.image.description` key in the `annotations` field of the manifest, as follows.
+
+```json
+"annotations": {
+  "org.opencontainers.image.description": "My multi-arch image"
+}
+```
+
+For example, the following {% data variables.product.prodname_actions %} workflow step builds and pushes a multi-arch image. The `outputs` parameter sets the description for the image.
+
+```yaml
+{% data reusables.actions.actions-not-certified-by-github-comment %}
+
+- name: Build and push Docker image
+  uses: docker/build-push-action@ad44023a93711e3deb337508980b4b5e9bcdc5dc
+  with:
+    context: .
+    file: ./Dockerfile
+    platforms: {% raw %}${{ matrix.platforms }}{% endraw %}
+    push: true
+    outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image
+```

data/reusables/package_registry/about-annotation-keys.md

@@ -0,0 +1 @@
+You can use pre-defined annotation keys to add metadata including a description, a license, and a source repository to your container image.

data/reusables/package_registry/about-docker-labels.md

@@ -1 +0,0 @@
-You can use Docker labels to add metadata including a description, a license, and a source repository to your container image.