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

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

gcloud artifacts attachments list ^
    --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.
oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

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

oras discover --distribution-spec v1.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

gcloud artifacts attachments describe ATTACHMENT

Windows (PowerShell)

gcloud artifacts attachments describe ATTACHMENT

Windows (cmd.exe)

gcloud artifacts attachments describe ATTACHMENT
 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

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

gcloud artifacts attachments download ATTACHMENT ^
    --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.

oras pull -o DESTINATION ATTACHMENT_URI

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

oras pull -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

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

gcloud artifacts attachments delete ATTACHMENT
 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