自動執行建構作業，因應 Webhook 事件

Cloud Build 可讓您定義Webhook 觸發條件，驗證及接受連入的 Webhook 事件。這些事件會傳送至自訂網址，讓您透過 Webhook 事件，將外部系統和外部原始碼管理系統 (例如 Bitbucket.com、Bitbucket Server 或 GitLab) 直接連結至 Cloud Build。

使用 Webhook 觸發條件時，您可以在建立觸發條件時定義內嵌建構設定檔，而不需指定來源。透過內建建構設定，您可以控管 Git 作業，並定義建構作業的其餘部分。

本頁說明如何建立 Webhook 觸發條件，自動執行建構作業，因應 Webhook 事件。

事前準備

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • 如要在本頁面使用 gcloud 指令，請安裝 Google Cloud CLI。

建立 Webhook 觸發條件

主控台

如要透過 Google Cloud 控制台建立 Webhook 觸發條件，請按照下列步驟操作：

  1. 開啟「觸發條件」頁面：

    開啟「建構觸發條件」頁面

  2. 在頁面頂端選取專案，然後按一下「開啟」。

  3. 按一下「建立觸發條件」。

  4. 輸入下列觸發條件設定：

    • 名稱︰觸發條件的名稱。

    • 「區域」：選取觸發條件的區域。

    • 如果與觸發條件相關聯的建構設定檔指定了私人集區，Cloud Build 就會使用該私人集區執行建構作業。在這種情況下，您在觸發條件中指定的區域必須與您建立私人集區的區域相符。

    • 如果與觸發條件相關聯的建構設定檔未指定私人集區，Cloud Build 會使用預設集區，在與觸發條件相同的區域中執行建構。
      • 說明 (選填)：觸發條件的說明。
      • 「Event」(事件)：選取「Webhook event」(Webhook 事件)，設定觸發條件，以便在收到 Webhook 事件時啟動建構作業。

      • Webhook 網址：使用 Webhook 網址驗證連入的 Webhook 事件。

        • Secret：您需要 Secret 才能驗證傳入的 Webhook 事件。您可以建立新密鑰或使用現有密鑰。這個密碼與 SSH 金鑰相關聯的密碼不同。

          如要建立新密鑰，請按照下列步驟操作：

          1. 選取「使用新的密鑰 (由 Cloud Build 產生)」。

          2. 按一下「Create Secret」(建立密鑰)。

            系統會顯示「建立 Webhook 密鑰」彈出式方塊。

          3. 在「Secret name」(密鑰名稱) 欄位中，輸入密鑰的名稱。

          4. 按一下「建立密鑰」儲存密鑰，系統會自動建立密鑰並儲存在 Secret Manager 中。

            如要使用現有密鑰，請按照下列步驟操作：

          5. 選取「使用現有的密鑰或自行建立密鑰」。

          6. 在「密鑰」欄位中，從下拉式選單選取要使用的密鑰名稱，或按照操作說明依據資源 ID 新增密鑰。

          7. 在「密碼版本」欄位中，從下拉式選單選取密碼版本。

            如果您使用現有 Secret，可能需要手動將 Secret Manager Secret 存取者角色授予 Cloud Build 服務帳戶 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com。詳情請參閱「將 Secret Manager 角色授予服務帳戶」。

          建立或選取密鑰後，系統會顯示 Webhook 網址預覽畫面。網址會包含 Cloud Build 產生的 API 金鑰和密鑰。如果 Cloud Build 無法擷取 API 金鑰，您可以手動將 API 金鑰新增至網址，或瞭解如何取得 API 金鑰 (如果尚未取得)。

          你可以使用這個網址，透過 POST 方法發出 HTTP 要求，叫用 Webhook 事件。

          使用下列指令叫用 Webhook 事件：

          curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -d "{}"

          完成這些步驟後，系統會自動將 Secret Manager 密鑰存取者角色授予 Cloud Build 服務代理程式 service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com。如果系統未自動將這個角色新增至服務代理人，請按照「為服務帳戶授予 Secret Manager 角色」一文中的步驟操作。

      • 來源 (選用)：選取在執行 Webhook 觸發條件時要建構的來源。如果您指定內建建構設定，則不必指定下列來源。你可以指定第 1 代或第 2 代做為來源。詳情請參閱 Cloud Build 存放區。

        • 存放區：從可用存放區清單中選取所需存放區。

        • 分支版本或標記：指定要比對分支版本或標記值的規則運算式。如要瞭解可接受的規則運算式語法，請參閱 RE2 語法。

        • 註解控制：如果您選取「提取要求 (僅限 GitHub 應用程式)」做為事件，請選擇下列其中一個選項，控管觸發條件是否會自動執行建構作業：

          • 必要 (擁有者和協作者除外)：存放區擁有者或協作者建立或更新提取要求時，觸發條件會自動執行建構作業。如果外部貢獻者發起動作，只有在擁有者或協作者對提取要求加註 /gcbrun 時，才會執行建構作業。

          • 必要：當任何貢獻者建立或更新提取要求時，只有在擁有者或協作者對提取要求加上 /gcbrun 註解後，系統才會執行建構作業。每當提取要求有變更時，系統就會執行建構作業。

          • 不需設定：任何貢獻者建立或更新提取要求時，觸發程序會自動執行建構作業。

      • 設定：選取遠端存放區中的建構設定檔，或建立內嵌建構設定檔，以用於建構作業。如果未指定來源存放區，則必須選取「內嵌」建構設定檔做為設定選項。

        • 類型：選取要用於建構作業的設定類型。
          • Cloud Build 設定檔 (YAML 或 JSON)： 使用建構設定檔進行設定。
          • Dockerfile：使用 Dockerfile 進行設定。
          • Buildpacks：使用建構包進行設定。

        • 位置：指定設定的位置。

          • 存放區：如果設定檔位於遠端存放區，請提供建構設定檔、Dockerfile 目錄或建構套件目錄的位置。如果建構設定類型為 Dockerfile 或建構包，您需要為產生的映像檔提供名稱，並視需要設定建構作業的逾時時間。提供 Dockerfile 或建構套件映像檔名稱之後，您會看見建構將執行的 docker build 或 pack 指令預覽。
          • Buildpack 環境變數 (選用)：如果您選取 buildpacks 做為設定類型，請按一下「新增套件環境變數」，指定 buildpack 環境變數和值。如要進一步瞭解建構包環境變數，請參閱「環境變數」。

          • 內嵌：如果您選取「Cloud Build 設定檔 (yaml 或 json)」做為設定選項，可以內嵌指定建構設定。按一下「開啟編輯器」，在Google Cloud 控制台中使用 YAML 或 JSON 語法編寫建構設定檔。按一下「完成」即可儲存建構設定。

          在下列範例中，內建建構設定檔會記錄「hello world」的 echo：

           steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']

      • 替換 (選用)：如果您選取建構設定檔做為建構設定選項，或建立內嵌建構設定檔，可以使用這個欄位定義觸發條件專用的替換變數。定義替代變數值時，您也可以使用酬載繫結取得資料。

      • 篩選器 (選用)：您可以在觸發條件中建立規則，根據替代變數判斷觸發條件是否會執行建構作業。

      1. 按一下「建立」即可建立建構觸發條件。

    gcloud

    (選用) 取得 API 金鑰

    如要驗證連入的 Webhook 事件，需要使用 API 金鑰。

    取得 API 金鑰的方法如下：

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

      開啟「憑證」頁面

    2. 按一下 [Create credentials] (建立憑證)。

    3. 點選「API 金鑰」。

      畫面上會顯示一個對話方塊，其中包含您建立的 API 金鑰。記下 API 金鑰。

    4. 如要限制金鑰用於產品應用程式，請按一下「限制金鑰」，完成額外步驟來保護金鑰安全。否則請按一下「關閉」。

      如要瞭解如何限制金鑰，請參閱「套用 API 金鑰限制」。

    (選用) 將 Secret Manager 角色授予服務帳戶

    Cloud Build 會在設定密鑰時，自動將 Secret Manager Secret Accessor 角色授予需要該角色的服務帳戶。如果系統未自動將這個角色授予必要的服務帳戶，請完成下列步驟，手動新增角色，讓服務帳戶可以存取密鑰：

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

      開啟 IAM 頁面

    2. 選用：如要查看 Google 提供的帳戶，請勾選「包含 Google 提供的角色授予項目」核取方塊。

    3. 記下要授予角色的建構服務帳戶。

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

      開啟 Secret Manager 頁面

    5. 按一下密鑰名稱。

      畫面中會顯示「Secret details」(密鑰詳細資料) 頁面。

      1. 按一下 [權限] 分頁標籤。

      2. 點選「授予存取權」。

        系統會顯示「授予存取權」面板。

      3. 在「新增主體」部分，新增與建構服務帳戶相關聯的電子郵件地址。

      4. 在「指派角色」部分，依序選取「Secret Manager」 >「Secret Manager Secret Accessor」。

      5. 按一下 [儲存]。

    後續步驟