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 或 Protocol Buffers)。

為 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
  • 通訊協定緩衝區

通知資料

每個 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 後，存放區的事件訊息就會顯示在其他專案的主題中。