Configuring Cloud Pub/Sub notifications

You can receive notifications of changes to your Google Cloud Platform (GCP) repositories by using Cloud 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 GCP project.

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

Before you begin

• If you haven't already done so, follow the steps in the quickstart for adding notifications to create a project, install Git, and initialize the Cloud SDK.
• 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 Cloud Pub/Sub notifications for Cloud Source Repositories.

Create a Cloud Pub/Sub topic

For each Cloud Source Repositories project or repository for which you'd like notifications, you need to create a Cloud Pub/Sub topic. You can create a topic using either the Google Cloud Platform 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 GCP project ID.
• [TOPIC_NAME] is the name of the topic.

To create a topic, follow these steps.

Console

1. In the GCP Console, go to the Cloud Pub/Sub Topics page.

   Go to the Topics page

2. Click Create Topic.

3. Enter a topic name with the URI:

   projects/[PROJECT_ID]/topics/[TOPIC_NAME]
   

   Where:

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

4. Click Create.

   The Topic details page opens.

gcloud

In a terminal window, run the following command:

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

Where:

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

Note: If this command returns a Resource already exists in the project error, you might already have a Cloud Source Repositories topic.

To learn more about the gcloud pubsub topics command, see the topics documentation.

Create a Cloud Pub/Sub subscription

To receive events published to a topic, you need to create a Cloud 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.

Console

1. In the GCP Console, go to the Cloud Pub/Sub Topics page.

   Go to the Topics page

2. Click the name of your project's topic.

3. Click Create Subscription.

   The Add subscription to topic page opens.

4. Enter a subscription name:

   projects/[PROJECT_ID]/subscriptions/[SUBSCRIPTION_NAME]
   

   Where:

   • [PROJECT_ID] is your GCP project ID.
   • [SUBSCRIPTION_NAME] is the name of the Cloud Pub/Sub subscription.

5. Leave Delivery type set to Pull.

6. Click Create.

gcloud

In a terminal window, run the following command:

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

Where:

• [SUBSCRIPTION_NAME] is the name of the Cloud Pub/Sub subscription.
• [TOPIC_NAME] is the name of the topic.

Note: Use the optional flag --ack-deadline to configure how many seconds the system waits for acknowledgement from the subscriber before re- attempting delivery. Without this flag, the default deadline is 10 seconds.

To learn more about the gcloud pubsub subscriptions command, see the subscriptions documentation.

Add a topic

You can associate a Cloud Pub/Sub topic with a GCP project or repository by using the gcloud command-line tool.

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 Cloud 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 GCP repository.
• [TOPIC_NAME] is the name of the Cloud 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.

Note: For information on how to delete a Cloud Pub/Sub topic, see Managing topics and subscriptions.

Remove a topic

You can remove an association between a project or repository and a Cloud Pub/Sub topic by using the gcloud command-line tool.

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]

Note: For information on how to delete a Cloud Pub/Sub topic, see Managing topics and subscriptions.

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