From a9188ee4d1e1f1bd376e28ead98fc5fc9f7ed9d5 Mon Sep 17 00:00:00 2001 From: github-openapi-bot <69533958+github-openapi-bot@users.noreply.github.com> Date: Mon, 9 Jan 2023 01:38:40 -0800 Subject: [PATCH 1/2] Update OpenAPI Descriptions (#33825) Co-authored-by: github-openapi-bot From a5019c4ec7087dbca61fc6c50fd526f759cfc9a9 Mon Sep 17 00:00:00 2001 From: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com> Date: Mon, 9 Jan 2023 11:00:00 +0000 Subject: [PATCH 2/2] [Improvement] Document how to add a description to a multi-arch image (#33759) Co-authored-by: Lucas Costi --- .../publishing-docker-images.md | 2 +- .../working-with-the-container-registry.md | 42 +++++++++++++++++-- .../package_registry/about-annotation-keys.md | 1 + .../package_registry/about-docker-labels.md | 1 - 4 files changed, 40 insertions(+), 6 deletions(-) create mode 100644 data/reusables/package_registry/about-annotation-keys.md delete mode 100644 data/reusables/package_registry/about-docker-labels.md diff --git a/content/actions/publishing-packages/publishing-docker-images.md b/content/actions/publishing-packages/publishing-docker-images.md index 8f521c2664..5fe4024a0a 100644 --- a/content/actions/publishing-packages/publishing-docker-images.md +++ b/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 %} diff --git a/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md b/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md index 6f00ec0d2e..b5072fae2c 100644 --- a/content/packages/working-with-a-github-packages-registry/working-with-the-container-registry.md +++ b/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 +``` \ No newline at end of file diff --git a/data/reusables/package_registry/about-annotation-keys.md b/data/reusables/package_registry/about-annotation-keys.md new file mode 100644 index 0000000000..94ed68f23b --- /dev/null +++ b/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. diff --git a/data/reusables/package_registry/about-docker-labels.md b/data/reusables/package_registry/about-docker-labels.md deleted file mode 100644 index 88c689c613..0000000000 --- a/data/reusables/package_registry/about-docker-labels.md +++ /dev/null @@ -1 +0,0 @@ -You can use Docker labels to add metadata including a description, a license, and a source repository to your container image.