Manage artifact metadata

This page describes how to manage metadata related to an artifact stored in Artifact Registry as an attachment.

Attachments are files that store metadata about a related artifact stored in Artifact Registry. To learn how to create an attachment, see Store artifact metadata in attachments.

Before you begin

Optional: Configure defaults for Google Cloud CLI commands.

Required roles

To get the permissions that you need to manage attachments, ask your administrator to grant you the following IAM roles on the repository:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

List attachments

An artifact in Artifact Registry can have any number of attachments that refer to it. You can list attachments by using the Google Cloud console, the gcloud CLI, or, for Docker-format container images only, Oras.

Console (Docker only)

  1. In the Google Cloud console, open the Repositories page.

    Open the Repositories page

  2. Click the repository name to see images in your repository.

  3. To see the versions of an image, click the image name.

  4. Click the appropriate image version.

  5. To see the attachments for that version, click the Attachments tab.

gcloud

Before using any of the command data below, make the following replacements:

  • TARGET: the fully qualified version name. For Docker images only, you can also use the Artifact Registry URI of the artifact the attachment refers to. In the URI, you can use the digest or, for Docker images, the tag—for example, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudartifactsattachmentslist\
--target=TARGET

Windows (PowerShell)

gcloudartifactsattachmentslist`
--target=TARGET

Windows (cmd.exe)

gcloudartifactsattachmentslist^
--target=TARGET
 For more information, see the gcloud artifacts attachments list command.

Oras (Docker only)

Before running the command, make the following replacement:

  • IMAGE_URI: the URI of the target image referred to by any listed attachments.
orasdiscover--distribution-specv1.1-referrers-apiIMAGE_URI

The following example lists attachments for a container image, my-image, identified by its URI and tag:

orasdiscover--distribution-specv1.1-referrers-api\
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Where:

  • v1.1-referrers-api is the Referrer API used. For more information, see the details in the distribution spec.

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 is the URI including the tag of the container image version to list attachments for.

For a full guide and more examples, see the oras discover documentation.

Describe attachments

Before using any of the command data below, make the following replacements:

  • ATTACHMENT: the fully qualified name of the attachment, such as projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Alternatively, provide only the attachment ID and use the --location and --repository flags.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudartifactsattachmentsdescribeATTACHMENT

Windows (PowerShell)

gcloudartifactsattachmentsdescribeATTACHMENT

Windows (cmd.exe)

gcloudartifactsattachmentsdescribeATTACHMENT
 For more information, see the gcloud artifacts attachments describe command.

Download attachments

You can download attachments by using the gcloud CLI or, for Docker-format container images only, Oras.

gcloud

Before using any of the command data below, make the following replacements:

  • ATTACHMENT: the fully qualified name of the attachment, such as projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Alternatively, provide only the attachment ID and use the --location and --repository flags.
  • DESTINATION: the path in your local file system to download the attachment to.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudartifactsattachmentsdownloadATTACHMENT\
--destination=DESTINATION

Windows (PowerShell)

gcloudartifactsattachmentsdownloadATTACHMENT`
--destination=DESTINATION

Windows (cmd.exe)

gcloudartifactsattachmentsdownloadATTACHMENT^
--destination=DESTINATION
 For attachments in Docker-format repositories, as an alternative to providing ATTACHMENT, you can provide the --oci-version-name flag followed by the attachment's full version name or Artifact Registry URI. You can use either the digest or the tag—for example, projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123.

For more information, see the gcloud artifacts attachments download command.

Oras (Docker only)

Before running the command, make the following replacements:

  • DESTINATION: the destination directory for your attachment.

  • ATTACHMENT_URI: the URI of the attachment to download. This is the URI for the image container the attachment refers to, followed by the attachment's unique SHA.

oraspull-oDESTINATIONATTACHMENT_URI

The following example downloads an attachment identified by its URI and digest:

oraspull-o.us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

Where:

  • -o . names the current directory as the download destination.

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx is the image URI including the digest of the attachment to download.

For a full guide and more examples, see the oras pull documentation.

Delete attachments

You can delete attachments directly by using the Google Cloud console or the gcloud CLI. You can delete attachments indirectly by deleting the artifact it refers to.

Delete attachments directly

You can delete attachments directly with one of the following options:

Console (Docker only)

  1. In the Google Cloud console, open the Repositories page.

    Open the Repositories page

  2. Click the repository name to see images in your repository.

  3. Click the image name to see versions of that image.

  4. Click the version of the image you to see attachments for.

  5. Click the Attachments tab to see attachments for that version.

  6. Click the digest of the attachment to delete.

  7. Click DELETE.

  8. In the confirmation dialog, click DELETE.

gcloud

Before using any of the command data below, make the following replacements:

  • ATTACHMENT: the fully qualified name of the attachment, such as projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Alternatively, provide only the attachment ID and use the --location and --repository flags.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloudartifactsattachmentsdeleteATTACHMENT

Windows (PowerShell)

gcloudartifactsattachmentsdeleteATTACHMENT

Windows (cmd.exe)

gcloudartifactsattachmentsdeleteATTACHMENT
 For more information, see the gcloud artifacts attachments delete command.

Delete attachments indirectly

If an artifact is deleted, all attachments with the deleted artifact's version name as their target are also deleted. This applies to both the manual deletion of artifacts and to deletions caused by cleanup policies.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月29日 UTC.