.
Console
Start free

Store artifact metadata in attachments

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

Metadata stored in attachments can include information about artifact vulnerabilities, build provenance, package contents, certification, vulnerability assessment, Software Bill of Materials (SBOM) and more. Information stored in Artifact Registry attachments can be used by policy systems and inspected by users to ensure compliance.

For more information about working with attachments, see Manage metadata with attachments.

Before you begin

  1. If you don't already have one, create a standard-mode repository.
  2. (Optional) Configure defaults for Google Cloud CLI commands.

Required roles

To get the permissions that you need to create attachments, ask your administrator to grant you the Artifact Registry Writer (roles/artifactregistry.writer) IAM role 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.

Create an attachment

For Docker repositories, attachments must be OCI artifacts. For all formats other than Docker, attachments can be any file type.

To create an attachment, complete the following steps:

gcloud (all formats)

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

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --attachment-type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows (PowerShell)

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --attachment-type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows (cmd.exe)

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --attachment-type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES
 For more information, see the gcloud artifacts attachments create command.

Oras (Docker only)

When creating an attachment with Oras, Artifact Registry generates a random UUID to use as the attachment name.

Before using Oras, complete the following steps:

  1. Install Oras 1.2 or later. To verify your version, run the oras version command.

  2. Configure Oras to authenticate with Artifact Registry.

Before running the command, make the following replacements:

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

The following example creates an attachment consisting of a file, hello-world.txt, that refers to a container image, my-image, identified by its URI and tag:

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

Where:

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

Manage attachments with cleanup policies

Docker repository attachments, including build provenance, are deleted when artifacts they're attached to are deleted. If you use cleanup policies to delete images from your repository, then by default, the attachments on those images will be deleted as well.

To ensure that attachments you want to keep aren't accidentally deleted by a cleanup policy, you can assign a tag to an image that has attachments you want to keep. Then, you can configure a cleanup policy to retain images with those tags. For example, you could assign a production-signed tag to images with attached build provenance.

what's next