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 时,代码库的事件消息将出现在另一个项目的主题中。