Configuring Cloud Pub/Sub notifications

You can receive notifications of changes to your GCP repositories 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 or across an entire project.

To learn more about Cloud Pub/Sub, see the What is Google Cloud Pub/Sub? topic.

Before you begin

• If you have not already done so, follow the steps in the Quickstart to create a project, install Git, and initialize the Google Cloud SDK.
• Verify that you have the appropriate permissions to create topics and subscriptions. For more information, see Access Control.
• Make sure that 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 Google 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 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 Platform project ID and [TOPIC_NAME] is the name of the topic.

To create a topic:

Console

1. Go to the Cloud Pub/Sub topics page in the GCP Console.

   Go to the Cloud Pub/Sub 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 Google Cloud Platform project ID.

4. Click Create.

gcloud

From a terminal window, run the following command:

gcloud alpha pubsub topics create projects/[PROJECT-ID]/topics/[TOPIC_NAME]

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

To learn more about the gcloud alpha 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 Pub/Sub subscription.

A subscriber application 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:

Console

1. Go to the Cloud Pub/Sub topics page in the GCP Console.

   Go to the Cloud Pub/Sub topics page

2. Click your project's topic.

3. Click Create Subscription.

4. Enter a subscription name:

   projects/[PROJECT-ID]/subscriptions/[SUBSCRIPTION_NAME]
   

   Leave Delivery Type set to Pull.

5. Click Create.

gcloud

From a terminal window, run the following command:

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

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

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

Add a topic

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

To add a topic to an entire project, type the following command:

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

To add a topic to a specific repository, type the following command:

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

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 is not 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 using the gcloud command-line tool.

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

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

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

gcloud beta 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 JSON or Protocol Buffers format. To set the format for a topic, you can use the --message-format parameter when you add the topic, such as:

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

You can also use the set-format command:

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

What's next

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