You can receive notifications fromPub/Sub for thechanges to a Docker repository. Notifications apply to any container imagestored in the repository, includingHelm 3 chartspackaged in OCI format.

Pub/Sub publishes messages about your repositories to namedresources calledtopics. Applications thatsubscribe to Pub/Subtopics receive these messages and receive notifications when a repository'sstate changes.

Artifact Registry publishes messages for the following changes:

• Image uploads
• New tags added to images
• Image deletion

Additionally, you can configure roles and permissions for publishing orsubscribing to notifications.

Overview

Artifact Registry publishes messages about changes to repositories in atopic namedgcr.

To receive notifications, you must:

1. Create a topic namedgcr in the project with Artifact Registry.
2. Create a subscription to the topic.
3. Set up yoursubscriber application to receivemessages about repository changes.
4. If appropriate,configure permissions to control accessto your topic and subscription.

Creating the Artifact Registry topic

To create thegcr topic with Google-owned and Google-managed encryption keys:

gcloudpubsubtopicscreategcr--project=PROJECT-ID

To create thegcr topic with CMEK encryption, see the Pub/Subinstructions for encrypting topics.

After you have have created thegcr topic or verified that it exists, you cancreate asubscription to the topic.

Creating a subscription

After you havecreated a topic for repository changes, you canconfigure a subscription to it that uses eitherpush deliveryorpull delivery. We recommend using pull delivery sinceCI/CD systems can generate numerous changes to stored artifacts, and pulldelivery is more effective for a large volume of messages.

To create a subscription with pull delivery:

gcloudpubsubsubscriptionscreateSUBSCRIPTION-NAME--topic=gcr

You now have a subscription to thegcr topic. The next step isconfiguring permissions for the identities that trigger changesin repositories.

Configuring your subscriber application

After you havecreated a topic and asubscriptionto that topic, you can set up your subscriber application, the applicationthat receive messages about changes to repositories. Subscriber applicationsfulfill tasks like event notifications, system logging,and communication between applications.

When a repository user pushes or deletes an image, the following steps occur:

1. The Artifact Registry service account publishes the change to yourgcrtopic. The service account isservice-PROJECT-NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com,wherePROJECT-NUMBER is your Google Cloudproject number. TheArtifact Registry service account has thepubsub.topics.publishpermission by default so that it can publish changes to your topic.

   If an administrator has revoked thepubsub.topics.publish permissions forthe Artifact Registry service account, Artifact Registry attempts to publishthe message as the repository user. In this situation, the repository user'saccount must have thepubsub.topics.publish permission to successfullypublish the message.

2. Pub/Sub forwards the message from the topic to your subscription.

3. When your subscriber application makes a request for messages, it pullsthe new message from the subscription.

   The identity that pulls messages on behalf of the subscriber must havepermissions to access the subscription. You can use thePub/Sub Subscriber roleto grant this permission.

To learn about setting up a subscriber to receive messages from a subscriptionwith pull delivery, seeReceiving messages using Pull.

Configuring permissions

You can use Pub/Sub permissions to control access to your topics andsubscriptions.

For more information about Pub/Sub permissions and granting access totopics and subscriptions, see the Pub/Subaccess control documentation.

Notification examples

Pub/Sub sends notifications as JSON-formatted strings. Review thefollowing examples to learn what to expect when receiving Artifact Registry notifications from Pub/Sub.

When an image is pushed to Artifact Registry, the notificationpayload might look like this:

{  "action":"INSERT",  "digest":"us-west1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5..."}

When a new image tag is pushed to Artifact Registry, the notificationpayload looks like this:

{  "action":"INSERT",  "digest":"us-west1-docker.pkg.dev/my-project/my-repo/hello-world@sha256:6ec128e26cd5...",  "tag":"us-west1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"}

The message identifies the relevant image using either adigest ortag key.

When an image tag is deleted from Artifact Registry, the notificationpayload might look like this:

{  "action":"DELETE",  "tag":"us-west1-docker.pkg.dev/my-project/my-repo/hello-world:1.1"}

The message might contain eitherDELETE orINSERT as values for theactionkey.

What's next

• Read thePub/Sub documentation.
• For an in-depth explanation of Pub/Sub, seeWhat is Pub/Sub?
• Learn more aboutPub/Sub access control roles.