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. This can be configured for an entire GCP Project or an individual repository.


You can use Cloud Pub/Sub access control to configure permissions for your project and resources. You can use access controls to help secure event data that your repository generates.

You can configure Cloud Pub/Sub access controls in the GCP Console's IAM page or via the IAM API.

The Cloud Source Repositories uses the default Compute Engine service account to publish a notification to your Cloud Pub/Sub} topic. This service account has the permissions need to publish messages to Cloud Pub/Sub topics. You can select a different service account using the gcloud command-line tools.

To configure permissions for subscribing, use any of the following roles:

  • Owner
  • Editor
  • PubSub/Admin
  • PubSub/Editor
  • PubSub/Subscriber

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"
Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Source Repositories