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

主控台

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

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

   開啟「Build 觸發條件」頁面

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

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

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

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

   • 區域：選取觸發事件的區域。

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

   • 如果與觸發事件相關聯的建構設定檔「未」指定私人集區，Cloud Build 就會使用預設集區，在與觸發事件相同的區域中執行建構作業。

     • 說明 (選用)：觸發條件的說明。
     • 事件：選取「Webhook 事件」，即可設定觸發條件，以便在收到 Webhook 事件時啟動建構作業。

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

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

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

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

         2. 按一下「Create Secret」。

            畫面上會顯示「Create a webhook secret」彈出式視窗。

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

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

            如要使用現有密鑰：

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

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

         7. 在「Secret version」欄位中，從下拉式選單中選取機密金鑰版本。

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

         建立或選取密鑰後，您會看到 Webhook 網址預覽。您的網址會包含 Cloud Build 產生的 API 金鑰和密鑰。如果 Cloud Build 無法擷取 API 金鑰，您可以手動將 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 觸發事件時要建構的來源。如果您要指定內嵌建構設定，則不必指定下列來源。您可以指定「1st generation」或「2nd generation」做為來源。詳情請參閱「Cloud Build 存放區」。

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

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

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

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

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

         • 非必要：當任何貢獻者建立或更新提取要求時，系統會自動執行建構作業。

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

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

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

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

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

         在以下範例中，內嵌建構設定檔會記錄「hello world」的回音：

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

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

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

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

   gcloud

   (選用) 取得 API 金鑰

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

   取得 API 金鑰的方法如下：

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

      開啟「憑證」頁面

   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. 在「Add Principals」部分，新增與建構服務帳戶相關聯的電子郵件地址。

      4. 在「Assign roles」(指派角色) 專區中，依序選取「Secret Manager」 >「Secret Manager Secret Accessor」。

      5. 按一下 [儲存]。

   後續步驟

   • 瞭解如何建立及管理觸發條件。
   • 瞭解如何建構託管於 Bitbucket Server 的存放區。
   • 瞭解如何手動啟動版本。
   • 瞭解如何查看建構結果。
   • 瞭解如何排解建構錯誤。