Notifications for Cloud Source Repositories

Cloud Source Repositories publishes messages about your repository to named resources called topics. Apps subscribed to Pub/Sub topics can receive these messages. For example, when your repository state changes, you can receive an alert. Additionally, you can configure roles and permissions for your Pub/Sub topics to control how users interact with the Pub/Sub events that your repository generates.

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

Scope

You can configure Cloud Source Repositories to publish events to a Pub/Sub topic. You can set the scope of this configuration to be your entire Google Cloud project or an individual repository.

After it is configured, Cloud Source Repositories publishes messages to the specified Pub/Sub topic using your service account. You must first give the service account permissions to publish to the topic. If you have audit logging enabled for Pub/Sub, this service account is shown as the caller of the Pub/Sub APIs.

Permissions

Configuring Cloud Source Repositories to publish messages requires the following:

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

When you configure Cloud Source Repositories for Pub/Sub, you must have these 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 Pub/Sub topic is registered, the specified service account must have pubsub.topics.publish permission to publish a message.

Event types

Pub/Sub can notify you when a user creates a repository, deletes a repository, or pushes a commit to a repository. Each event is a specific event type. The following table lists the types and their corresponding definitions.

Event type 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 Pub/Sub to use one of two formats for notifications:

  • JSON
  • Protocol Buffers

Notification data

Each 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 containing 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 refUpdates field contains the following details about the git push command:

Field name Description
refName The name of the branch.
updateType The type of update. For more information, see Update types.
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 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": "someone@somecompany.com",
      "refUpdates": {
        "refs/heads/master": {
          "refName": "refs/heads/master",
          "updateType": "UPDATE_FAST_FORWARD",
          "oldId": "c7a28dd5de3403cc384a025834c9fce2886fe763",
          "newId": "f00768887da8de62061210295914a0a8a2a38226"
        }
      }
    }
  }

Cross-project setup 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 Pub/Sub topic, give the role roles/pubsub.publisher to this service account. When you configure Cloud Source Repositories with this account and this Pub/Sub topic, the event messages for your repository appear in the topic in the other project.