Cloud Source Repositories 的通知

Cloud Source Repositories 将关于您的代码库的消息发布到名为主题的指定资源上。订阅 Pub/Sub 主题的应用可以接收这些消息。例如，当您的代码库状态更改时，您会收到警报。另外，您可以为 Pub/Sub 主题配置角色和权限，以控制用户如何与代码库生成的 Pub/Sub 事件进行交互。

此页面概述了 Cloud Source Repositories 的 Pub/Sub 通知。要了解如何设置和使用 Pub/Sub 通知，请参阅 配置 Pub/Sub 通知。

范围

您可以配置 Cloud Source Repositories 以发布事件到 Pub/Sub 主题。您可以将此配置的范围设置为整个 Google Cloud 项目或单个代码库。

配置完成后，Cloud Source Repositories 使用您的服务账号将消息发布到指定的 Pub/Sub 主题。您必须首先授予服务账号发布该主题的权限。如果您为 Pub/Sub 启用了审核日志记录，则该服务账号将显示为 Pub/Sub API 的调用方。

权限

配置 Cloud Source Repositories 以发布消息需要执行以下操作：

  • 监视事件的项目或代码库。如果指定了项目，则将监视该项目下的所有代码库。
  • Cloud Source Repositories 将消息发布到的 Pub/Sub 主题。
  • 用于访问 Pub/Sub 主题的服务账号。
  • 消息格式（例如 JSON 或协议缓冲区）。

为 Pub/Sub 配置 Cloud Source Repositories 时，必须具有以下权限：

  • 指定代码库上的 source.repos.updateRepo 或指定项目上的 source.repos.updateProjectConfig
  • 指定服务账号上的 iam.serviceAccounts.actAs

注册Pub/Sub 主题后，指定的服务账号必须具有 pubsub.topics.publish 权限才能发布消息。

事件类型

当用户创建代码库，删除代码库或将提交推送到代码库时，Pub/Sub 可以通知您。每个事件都是特定的事件类型。下表列出了类型及其相应的定义。

事件类型 说明
CreateRepo 用户创建代码库时发生的事件。
RefUpdate 用户执行 git push 命令时发生的事件。
DeleteRepo 用户删除代码库时发生的事件。

通知格式

您可以配置 Pub/Sub 以使用两种格式的通知之一：

  • JSON
  • Protocol Buffers

通知数据

每个 Pub/Sub 通知都包含以下事件信息：

字段名称 说明
name 代码库名称。
url 代码库网址。
eventTime 发生更改的时间。
refUpdateEvent 具体更改的信息。
createRepoEvent 指示用户是否创建了代码库
deleteRepoEvent 指示用户是否删除了代码库

如果通知是针对 git push 命令的，则包含 refUpdateEvent 字段的通知将包含以下信息：

字段名称 说明
email 进行更改的用户的电子邮件地址。
refUpdates 关于提交的信息。

refUpdates 字段包含有关 git push 命令的以下详细信息：

字段名称 说明
refName 分支名称。
updateType 更新类型。有关详情，请参阅 更新类型。
oldId 代码库前一提交的 ID。
newId 代码库的新 ID。

更新类型

git push 事件可以具有四种更新类型之一。您可以在通知的 updateType 字段中找到类型。

更新类型 说明
CREATE 命令创建新引用时发生。
UPDATE_FAST_FORWARD 命令更新对象时发生。
UPDATE_NON_FAST_FORWARD 当命令使用 -f 标志（例如 git push -f）时发生。
删除 命令删除引用时发生。

通知示例

以下是 Pub/Sub 通知中包含的数据的示例。此通知使用 JSON 格式。

  {
    "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"
        }
      }
    }
  }

跨项目设置示例

您可以配置 Cloud Source Repositories 以将消息发布到另一个项目中的主题。在这种情况下，您必须在代码库所在的同一项目中创建一个服务账号。在包含 Pub/Sub 主题的项目中，将角色 roles/pubsub.publisher 赋予该服务账号。当使用此账号和 Pub/Sub 主题配置 Cloud Source Repositories 时，代码库的事件消息将出现在另一个项目的主题中。