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.

Note: If mirroring repositories to Cloud Source Repositories, the email address in Pub/Sub notifications always appears as [e-mail].

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": "[e-mail]",
      "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.