When changes are made to your Container Registry repository, such as whenimages are pushed, tagged, or deleted, you can receive notifications usingPub/Sub.

Pub/Sub publishes messages about your repository to namedresources calledtopics. These messages are received by applicationssubscribed to Pub/Sub topics. Subscriber applications sendnotifications when your repository's state changes.

Additionally, you can configure roles and permissions for yourPub/Sub topics to control how users interact with your repository.

To support the transition from Container Registry toArtifact Registry, Artifact Registry publishes messagesto the same topic as Container Registry.

For information about configuring Artifact Analysis notifications foractivity such as new vulnerability scan results, see theArtifact Analysis documentation.

Create a Pub/Sub topic

When you activate the Container Registry API in a Google Cloud project,Container Registry automatically creates a Pub/Subtopic with the topic IDgcr.

If thegcr topic was accidentally deleted or is missing, you can add ityourself. For example, the topic might be missing if your Google Cloudorganization has anorganization policy constraint that requiresencryption with customer-managed encryption keys (CMEK). When thePub/Sub API is in the deny list of this constraint,services cannot automatically create topics with Google-owned and Google-managed encryption keys.

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

gcloud pubsub topics create gcr --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.

Create a Pub/Sub subscription

Every Pub/Sub topic should have a subscription.

Asubscriber applicationreceives messages from your repository's topic. Subscribers fulfill tasks likeevent notifications, system logging, and communication betweenapplications.

Subscriptions can be configured to use apush modelor apull model.

To create a subscription:

gcloud pubsub subscriptions create [SUBSCRIPTION-NAME] --topic=gcr

Configuring Pub/Sub permissions

UsePub/Sub access controlto configure permissions for your project and resources. Access controls keepyour repository secure and allow you to manage user permissions using role-basedaccess.

You can configure Pub/Sub access controls in the Google Cloud console's IAM pageor via theIAM API.

• To configure permissions for publishing, use any of thefollowing roles: owner, editor, pubsub.admin, pubsub.editor, pubsub.publisher.Principals that push images or delete images from the registry must havethepubsub.topics.publish permission to publish a message toPub/Sub.

• To configure permissions for subscribing, use any of the followingroles: owner, editor, pubsub.admin, pubsub.editor, pubsub.subscriber.

Notification examples

Notifications are sent as JSON-formatted strings. Below are examples of what toexpect when receiving Container Registry notifications fromPub/Sub.

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

{"action":"INSERT","digest":"gcr.io/my-project/hello-world@sha256:6ec128e26cd5..."}

When a new tag is pushed to Container Registry, the notification payloadmight look like this:

{"action":"INSERT","digest":"gcr.io/my-project/hello-world@sha256:6ec128e26cd5...","tag":"gcr.io/my-project/hello-world:1.1"}

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

When a tag is deleted from Container Registry, the notification payloadmight look like this:

{  "action":"DELETE",  "tag":"gcr.io/my-project/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.