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.

You can use the gcloud CLI or Oras to create attachments in Docker-format repositories.

To create an attachment, complete the following steps:

gcloud (all formats)

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.
  • 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.
  • TYPE: the attachment's type attribute. For Docker images, the type must comply with OCI specifications for the artifactType property.
  • ATTACHMENT_NAMESPACE: a variable specific to attachments that identifies the attachment data source, such as example.com.
  • FILES: a comma-separated list of local files to include in the attachment.

      • 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:

  • ARTIFACT_TYPE: the artifactType of the attachment.

  • IMAGE_URI: the URI for the image container the attachment refers to.

  • FILE: a local file to include as metadata in the attachment.

  • MEDIA_TYPE: the mediaType of the layer.

  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:

  • doc/example defines the artifactType property of the attachment.

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

  • hello-world.txt is the local file that the attachment will hold as its data.

  • application/vnd.me.hi defines the mediaType of the layer.

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