設定 Google Chat 通知

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Cloud Build 可以將通知傳送至所選管道 (例如 Slack 或 SMTP 伺服器)，以便通知您建構作業更新。本頁面說明如何使用 Google Chat 通知器設定通知。

事前準備

• Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

  Enable the APIs

• 安裝 Google Cloud CLI。

設定 Google Chat 通知

以下說明如何使用 Google Chat 通知器手動設定 Google Chat 通知。如果您想改為自動化設定，請參閱「自動化處理通知設定」。

如何設定 Google Chat 通知：

1. 在 Google Chat 中建立聊天室。

2. 在建立的聊天室中，建立傳入 Webhook，以便將 Cloud Build 的訊息發布到 Google Chat。網址應類似於以下內容：

   https://chat.googleapis.com/v1/spaces/...
   

3. 將連入 Webhook 網址儲存在 Secret Manager 中：

   1. 在 Google Cloud 控制台中開啟「Secret Manager」頁面：

      開啟 Secret Manager 頁面

   2. 按一下「Create secret」。

   3. 輸入密鑰的名稱。

   4. 在「私密值」下方，新增 Google Chat 聊天室的傳入 Webhook 網址。

   5. 如要儲存密鑰，請按一下「建立密鑰」。

4. 雖然 Cloud Run 服務帳戶可能具備專案的編輯者角色，但編輯者角色不足以存取 Secret Manager 中的機密資料。如要讓 Cloud Run 服務帳戶存取機密，請按照下列步驟操作：

   1. 前往 Google Cloud 控制台的「IAM」頁面：

      開啟 IAM 頁面

   2. 找出與專案相關聯的 Compute Engine 預設服務帳戶：

      Compute Engine 預設服務帳戶的畫面會類似下圖：

      project-number[email protected]
      

      記下 Compute Engine 預設服務帳戶。

   3. 在 Google Cloud 控制台中開啟「Secret Manager」頁面：

      開啟 Secret Manager 頁面

   4. 按一下包含 Google 聊天 webhook 密鑰的密鑰名稱。

   5. 在「權限」分頁中，按一下「新增成員」。

   6. 將與專案相關聯的 Compute Engine 預設服務帳戶新增為成員。

   7. 選取「Secret Manager 密鑰存取者」權限做為角色。

   8. 按一下 [儲存]。

5. 授予 Cloud Run 服務帳戶讀取 Cloud Storage 值區的權限：

   1. 前往 Google Cloud 控制台的「IAM」頁面：

      開啟 IAM 頁面

   2. 找出與專案相關聯的 Compute Engine 預設服務帳戶：

      Compute Engine 預設服務帳戶的畫面會類似下圖：

      project-number[email protected]
      

   3. 按一下包含 Compute Engine 預設服務帳戶的資料列中的鉛筆圖示。您會看到「編輯存取權」分頁。

   4. 按一下 [Add another role] (新增其他角色)。

   5. 新增下列角色：

      • Storage 物件檢視者

   6. 按一下 [儲存]。

6. 撰寫通知器設定檔，設定 Google 聊天通知器和建構事件篩選器：

   在以下通知器設定檔範例中，filter 欄位會使用 Common Expression Language 搭配可用的變數 build，藉此篩選具有 SUCCESS 狀態的建構事件：

   apiVersion: cloud-build-notifiers/v1
   kind: GoogleChatNotifier
   metadata:
     name: example-googlechat-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       delivery:
         webhookUrl:
           secretRef: webhook-url
     secrets:
     - name: webhook-url
       value: projects/project-id/secrets/secret-name/versions/latest
   

   其中：

   • webhook-url 是本例中用於參照儲存在 Secret Manager 中的 Google Chat webhook 網址路徑的設定變數。您在此指定的變數名稱，應與 secrets 下方的 name 欄位相符。
   • project-id 是 Google Cloud 專案的 ID。
   • secret-name 是包含 Google Chat webhook 網址的秘密名稱。

   如需查看範例，請參閱 Google Chat 通知器的通知器設定檔。

   如要瞭解可用於篩選的其他欄位，請參閱「Build」資源。如需其他篩選範例，請參閱「使用 CEL 篩選建構事件」。

7. 將通知器設定檔上傳至 Cloud Storage 值區：

   1. 如果您沒有 Cloud Storage 值區，請執行下列指令來建立值區，其中 bucket-name 是您要給予值區的名稱，必須符合命名規定。

      gcloud storage buckets create gs://bucket-name/
      

   2. 將通知器設定檔上傳至值區：

      gcloud storage cp config-file-name gs://bucket-name/config-file-name
      

      其中：

      • bucket-name 是值區的名稱。
      • config-file-name 是設定檔的名稱。

8. 將通知器部署至 Cloud Run：

    gcloud run deploy service-name \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \
      --no-allow-unauthenticated \
      --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
   

   其中：

   • service-name 是您要部署映像檔的 Cloud Run 服務名稱。
   • config-path 是 Slack 通知器 gs://bucket-name/config-file-name 的通知器設定檔路徑。
   • project-id 是 Google Cloud 專案的 ID。

   gcloud run deploy 指令會從 Cloud Build 專屬的 Artifact Registry 提取最新版本的代管映像檔。Cloud Build 支援通知器映像檔九個月。九個月後，Cloud Build 會刪除映像檔版本。如果您想使用先前的映像檔版本，請在 gcloud run deploy 指令的 image 屬性中，指定圖片標記的完整語意版本。您可以在 Artifact Registry 中找到先前的圖片版本和標記。

9. 授予 Pub/Sub 權限，以便在 Google Cloud 專案中建立驗證權杖：

    gcloud projects add-iam-policy-binding project-id \
      --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
      --role=roles/iam.serviceAccountTokenCreator
   

   其中：

   • project-id 是 Google Cloud 專案的 ID。
   • project-number 是您的 Google Cloud 專案編號。

10. 建立服務帳戶，代表您的 Pub/Sub 訂閱身分：

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
      --display-name "Cloud Run Pub/Sub Invoker"
    

    您可以使用 cloud-run-pubsub-invoker，或使用不同於 Google Cloud 專案中其他服務帳戶的名稱。

11. 將 Cloud Run Invoker 權限授予 cloud-run-pubsub-invoker 服務帳戶：

    gcloud run services add-iam-policy-binding service-name \
       --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
       --role=roles/run.invoker
    

    其中：

    • service-name 是您要部署映像檔的 Cloud Run 服務名稱。

    • project-id 是 Google Cloud 專案的 ID。

12. 建立 cloud-builds 主題，以便接收通知器的建構更新訊息：

    gcloud pubsub topics create cloud-builds
    

    您也可以在建構設定檔中定義自訂主題名稱，讓訊息改為傳送至自訂主題。在這種情況下，您會建立具有相同自訂主題名稱的主題：

    gcloud pubsub topics create topic-name
    

    詳情請參閱接收建構作業通知的 Pub/Sub 主題。

13. 為通知器建立 Pub/Sub 推播訂閱者：

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=service-url \
       --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
    

    其中：

    • subscriber-id 是您要為訂閱項目命名的名稱。
    • service-url 是 Cloud Run 為新服務產生的網址。
    • project-id 是 Google Cloud 專案的 ID。

您現在已設定 Cloud Build 專案的通知。下次叫用版本時，如果版本符合您設定的篩選器，您會在 Google Chat 中收到通知。

使用 CEL 篩選建構事件

Cloud Build 會在 Build 資源中列出的欄位上使用 CEL 和 build 變數，存取與建構事件相關聯的欄位，例如觸發 ID、映像檔清單或替換值。您可以使用 filter 字串，透過 Build 資源中列出的任何欄位，篩選建構設定檔中的建構事件。如要查看與欄位相關的確切語法，請參閱 cloudbuild.proto 檔案。

依觸發條件 ID 篩選

如要依觸發事件 ID 篩選，請使用 build.build_trigger_id 在 filter 欄位中指定觸發事件 ID 的值，其中 trigger-id 是觸發事件 ID 的字串：

filter: build.build_trigger_id == trigger-id

依狀態篩選

如要依狀態篩選，請使用 build.status 在 filter 欄位中指定要篩選的版本狀態。

以下範例說明如何使用 filter 欄位，篩選具有 SUCCESS 狀態的建構事件：

filter: build.status == Build.Status.SUCCESS

您也可以篩選不同狀態的版本。以下範例說明如何使用 filter 欄位篩選具有 SUCCESS、FAILURE 或 TIMEOUT 狀態的建構事件：

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

如要查看可用於篩選的其他狀態值，請參閱「Build」資源參考資料中的「狀態」。

依標記篩選

如要依標記篩選，請使用 build.tags 在 filter 欄位中指定標記的值，其中 tag-name 是標記的名稱：

filter: tag-name in build.tags

您可以使用 size，根據建構事件中指定的標記數量進行篩選。在以下範例中，filter 欄位會篩選出具備兩個標記的建構事件，其中一個標記指定為 v1：

filter: size(build.tags) == 2 && "v1" in build.tags

依圖片篩選

如要依圖片篩選，請使用 build.images 在 filter 欄位中指定圖片的值，其中 image-name 是 Artifact Registry 中列出的圖片完整名稱，例如 us-east1-docker.pkg.dev/my-project/docker-repo/image-one：

filter: image-name in build.images

在以下範例中，filter 會篩除建構事件，這些事件的 us-east1-docker.pkg.dev/my-project/docker-repo/image-one 或 us-east1-docker.pkg.dev/my-project/docker-repo/image-two 已指定為圖片名稱：

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images

依時間篩選

您可以透過在 filter 欄位中指定下列任一選項 (build.create_time、build.start_time 或 build.finish_time)，根據建構作業的建立時間、開始時間或結束時間篩選建構事件。

在以下範例中，filter 欄位會使用 timestamp 篩選建構事件，要求時間為 2020 年 7 月 20 日上午 6 點：

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

您也可以依據時間比較篩選建構事件。在以下範例中，filter 欄位會使用 timestamp 篩選建構事件，這些事件的開始時間介於 2020 年 7 月 20 日上午 6 點至 2020 年 7 月 30 日上午 6 點之間。

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

如要進一步瞭解 CEL 中時區的表示方式，請參閱 時區的語言定義。

如要依建構作業的時間長度篩選，您可以使用 duration 比較時間戳記。在以下範例中，filter 欄位會使用 duration 篩選建構事件，其中的建構作業必須執行至少五分鐘：

filter: build.finish_time - build.start_time >= duration("5m")

使用代入法進行篩選

您可以使用 build.substitutions 在 filter 欄位中指定替換變數，藉此篩選替換項目。在以下範例中，filter 欄位會列出包含替換變數 substitution-variable 的版本，並檢查 substitution-variable 是否與指定的 substitution-value 相符：

filter: build.substitutions[substitution-variable] == substitution-value

其中：

• substitution-variable 是替換變數的名稱。
• substitution-value 是替換值的名稱。

您也可以依預設替換變數值進行篩選。在下列範例中，filter 欄位會列出分支版本名稱為 master 的建構項目，以及存放區名稱為 github.com/user/my-example-repo 的建構項目。預設替代變數 BRANCH_NAME 和 REPO_NAME 會以鍵的形式傳遞至 build.substitutions：

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

如果您想使用規則運算式篩選字串，可以使用內建的 matches 函式。在以下範例中，filter 欄位會篩選狀態為 FAILURE 或 TIMEOUT 的建構，且這些建構也包含建構替換變數 TAG_NAME，且該變數的值與規則運算式 v{DIGIT}.{DIGIT}.{3 DIGITS}) 相符。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

如要查看預設替換值清單，請參閱「使用預設替換值」。

後續步驟

• 瞭解 Cloud Build 通知程式。
• 瞭解如何訂閱版本通知。
• 瞭解如何撰寫 Cloud Build 建構設定檔。