Configuring Pub/Sub notifications

You can receive notifications of changes to your Google Cloud repositories by using Pub/Sub. These notifications inform you when a user creates a new repository, deletes a repository, or pushes a change to an existing repository. You can choose to configure notifications for specific repositories or across an entire Google Cloud project.

To learn more about Pub/Sub, see What is Pub/Sub?

Before you begin

• If you haven't already done so, create a repository .
• Verify that you have the appropriate permissions to create topics and subscriptions. For more information, see Access control .
• Ensure you have a service account that can publish to your topic. By default, Cloud Source Repositories uses the Compute Engine default service account to publish messages. For more information, see Pub/Sub notifications for Cloud Source Repositories .

Create a Pub/Sub topic

For each Cloud Source Repositories project or repository for which you'd like notifications, you need to create a Pub/Sub topic. You can create a topic using either the Google Cloud console or the gcloud command-line tool.

When you create a topic, you need to use a qualified URI for your repository. The qualified URI is:

  projects 
 /[ 
 PROJECT_ID 
 ]/ 
 topics 
 /[ 
 TOPIC_NAME 
 ] 
 

Where:

• [PROJECT_ID] is your Google Cloud project ID.
• [TOPIC_NAME] is the name of the topic.

To create a topic, follow these steps.

  gcloud 
  
 pubsub 
  
 topics 
  
 create 
  
 projects 
 /[ 
 PROJECT_ID 
 ]/ 
 topics 
 /[ 
 TOPIC_NAME 
 ] 
 

Create a Pub/Sub subscription

To receive events published to a topic, you need to create a Pub/Sub subscription .

A subscriber app receives messages from your repository's topic. Subscribers can respond to your repository events by sending notifications or triggering a build.

To create a subscription, follow these steps.

  gcloud 
  
 pubsub 
  
 subscriptions 
  
 create 
  
 [ 
 SUBSCRIPTION_NAME 
 ] 
  
 --topic=[TOPIC_NAME] 
 

Add a topic

You can associate a Pub/Sub topic with a Google Cloud project or repository by using the Google Cloud CLI.

To associate a topic with an entire project, enter the following command:

  gcloud 
  
 source 
  
 project 
 - 
 configs 
  
 update 
  
 --add-topic=[TOPIC_NAME] --service-account=[SERVICE_ACCOUNT_NAME] 
 

Where:

• [TOPIC_NAME] is the name of the Pub/Sub topic.
• [SERVICE_ACCOUNT_NAME] is the name of your Cloud Build service account.

To associate a topic with a specific repository, enter the following command:

  gcloud 
  
 source 
  
 repos 
  
 update 
  
 [ 
 REPOSITORY_NAME 
 ] 
  
 --add-topic=[TOPIC_NAME] --service-account=[SERVICE_ACCOUNT_NAME] 
 

Where:

• [REPOSITORY_NAME] is the name of your Google Cloud repository.
• [TOPIC_NAME] is the name of the Pub/Sub topic.
• [SERVICE_ACCOUNT_NAME] is the name of your Cloud Build service account.

The service account must be in the same project as the repository, and it must have pubsub.topics.publish permission to publish a message on the specified topic. You must have iam.serviceAccounts.actAs permission on the service account. If the service account isn't specified, it defaults to the Compute Engine default service account.

Remove a topic

You can remove an association between a project or repository and a Pub/Sub topic by using the Google Cloud CLI.

To remove a topic from an entire project, enter the following command:

  gcloud 
  
 source 
  
 project 
 - 
 configs 
  
 update 
  
 --remove-topic=[TOPIC_NAME] 
 

To remove a topic from a specific repository, enter the following command:

  gcloud 
  
 source 
  
 repos 
  
 update 
  
 [ 
 REPOSITORY_NAME 
 ] 
  
 --remove-topic=[TOPIC_NAME] 
 

Set the topic format

Notifications for Cloud Source Repositories can use either the JSON or Protocol Buffers format. To set the format for a topic, you can use the --message-format parameter when you add the topic:

  gcloud 
  
 source 
  
 project 
 - 
 configs 
  
 update 
  
 --add-topic=[TOPIC_NAME] --message-format=[json|protobuf] 
 

You can also use the set-format command:

  gcloud 
  
 source 
  
 project 
 - 
 configs 
  
 update 
  
 --update-topic=[TOPIC_NAME] --message-format=[json|protobuf] 
 

What's next

• Learn more about Pub/Sub notifications for Cloud Source Repositories .
• Read the Pub/Sub documentation .
• For an in-depth explanation of Pub/Sub, see What is Pub/Sub? .
• Learn more about Pub/Sub access control roles .