Cloud Pub/Sub Notifications for Google Cloud Source Repositories

This page provides an overview of Cloud Pub/Sub Notifications for Google Cloud Source Repositories. To learn how to set up and use Cloud Pub/Sub Notifications, see Configuring Cloud Pub/Sub Notifications.

Cloud Source Repositories publishes messages about your repository to named resources called topics. These messages are received by applications subscribed to Cloud Pub/Sub topics. Subscriber applications receive notifications when your repository's state changes. Additionally, you can configure roles and permissions for your Cloud Pub/Sub topics to control how users interact with the Cloud Pub/Sub events that your repository generates.


You can configure Cloud Source Repositories to publish events to a Cloud Pub/Sub topic on your behalf. This can be configured for an entire Google Cloud Platform project or an individual repository.

After you have configured this, Cloud Source Repositories publishes messages to the specified Cloud Pub/Sub topic using your service account. The permissions required to publish a message on the topic must be given to this account. If you have audit logging enabled for Cloud Pub/Sub, this service account is shown as the caller of the Cloud Pub/Sub APIs.


The Cloud Source Repositories configuration requires:

  • A repository or a project to watch the repository events. If a project is specified, all repositories under that project are watched.
  • A Cloud Pub/Sub topic to publish messages.
  • A service account to access the Cloud Pub/Sub topic.
  • A message format (JSON or Protocol Buffers).

When you configure Cloud Source Repositories for Cloud Pub/Sub, you must have the following permissions:

  • source.repos.updateRepo on the specified repository or source.repos.updateProjectConfig on the specified project.
  • iam.serviceAccounts.actAs on the specified service account.

After the Cloud Pub/Sub topic is registered, the specified service account must have pubsub.topics.publish permission to publish a message.

Event types

You can use Cloud Pub/Sub notifications to track when a user creates a repository, deletes a repository, and pushes a commit to a repository. Each event has a specific event type. The following table lists the update types and their corresponding definitions.

EventType Description
CreateRepo Occurs when a user creates a repository.
RefUpdate Occurs when a user executes a git push command.
DeleteRepo Occurs when a user deletes a repository.

Notification Format

You can configure a Cloud Pub/Sub notification for Cloud Source Repositories to use one of two formats:

  • JSON
  • Protocol Buffers

Notification Data

Each Cloud Pub/Sub notification contains the following information about an event:

Field name Description
name Name of the repository.
url The URL of the repository.
eventTime The time at which the change occurred.
refUpdateEvent Information about the specific change.
createRepoEvent Indicates if a user created a repository
deleteRepoEvent Indicates if a user deleted a repository

If the notification is for a git push command, the notification contains the refUpdateEvent field contains the following information:

Field name Description
email The email address of the user who made the change.
refUpdates Information about the commit.

The refUpdate field contains the following details about the git push command:

Field name Description
refName The name of the branch.
updateType The type of update. See Update types for more information.
oldId The previous commit Id for the repository.
newId The new Id for the repository.

Update Types

A git push event can have one of four update types. You can find the type in the updateType field of the notification.

Update Type Description
CREATE Occurs when the command creates a new reference.
UPDATE_FAST_FORWARD Occurs when the command updates an object.
UPDATE_NON_FAST_FORWARD Occurs when the command uses the -f flag, such as git push -f.
DELETE Occurs when the command deletes a reference.

Notification Example

The following is an example of the data contained in a Cloud Pub/Sub notification. This notification uses the JSON format.

"name": "projects/test-project/repos/pubsub-test",
"url": "[URL_PATH]",
"eventTime": "2018-02-21T21:23:25.566175Z",
"refUpdateEvent": {
  "email": "",
  "refUpdates": {
    "refs/heads/master": {
    "refName": "refs/heads/master",
    "updateType": "UPDATE_FAST_FORWARD",
    "oldId": "c7a28dd5de3403cc384a025834c9fce2886fe763",
    "newId": "f00768887da8de62061210295914a0a8a2a38226"

Cross Project Set-Up Example

You can configure Cloud Source Repositories to publish a message to a topic in a different project. In this case, you must create a service account in the same project where your repository resides. In the project that contains the Cloud Pub/Sub topic, give the role roles/pubsub.publisher to this service account. When you configure Cloud Source Repositories with this account and this Cloud Pub/Sub topic, the event messages for your repository will appear in the topic in the other project.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Source Repositories Documentation