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

控制台

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

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

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

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

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

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

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

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

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

   • 說明 (選填)：觸發條件的說明。

   • 「Event」(事件)：選取「Webhook event」(Webhook 事件)，設定觸發條件，以便在收到 Webhook 事件時啟動建構作業。

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

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

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

     2. 點選「建立密鑰」。

        系統會顯示「Create a webhook secret」(建立 Webhook 密鑰) 對話方塊。

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

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

     如要使用現有密鑰：

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

     3. 在「Secret version」(密鑰版本) 欄位，從下拉式選單選取密鑰版本。

        如果您使用現有密鑰，可能需要手動將 Secret Manager 密鑰存取者角色授予 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 事件。

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

   • 來源 (選用)：如果您要指定內建建構設定，就不必指定來源。如果沒有，請按照下列步驟操作：

     • 存放區代別：選取 「第 2 代」。

     • 存放區：從可用存放區清單中，選取要建構的存放區。存放區的區域必須與觸發程序的區域相符。

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

     • 留言控制選項：如果選取「Pull request」(提取要求) 做為「Event」(事件)，請選擇下列其中一個選項，控管觸發條件是否自動叫用建構作業：

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

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

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

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

     • 類型：選取要用於建構作業的設定類型。

       • 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']
     

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

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

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

gcloud

如要建立 Webhook 觸發條件，請按照下列步驟操作：

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

其中：

• TRIGGER_CONFIG_PATH 是觸發條件設定檔的路徑。如果您使用觸發條件設定檔，則 name、description、region、secret、service-account、subscription-filter 和 substitution 欄位必須保持未定義狀態。詳情請參閱 Cloud Build 參考說明文件中的 BuildTrigger。
• TRIGGER_NAME 是觸發條件的名稱。
• DESCRIPTION (選用) 是觸發條件的說明。
• REGION 是觸發條件的區域。這個值必須是「global」以外的區域。
• SECRET_NAME 是您儲存在 Secret Manager 中的密鑰名稱。
• SECRET_VERSION 是與儲存在 Secret Manager 中的密鑰相關聯的版本。
• SERVICE_ACCOUNT 是用來執行與自動建構觸發條件相關的所有使用者控制作業的服務帳戶。如未定義服務帳戶，Cloud Build 會使用預設的 Cloud Build 服務帳戶。
• PROJECT_ID 是您的 Google Cloud 專案 ID。
• CONNECTION_NAME 是主機連線的名稱。
• REPO_NAME 是存放區的名稱。
• PATH_TO_BUILD_CONFIG 是建構設定檔的路徑。如果觸發程序參照 Cloud Build 存放區中的建構設定檔，請使用這項參數。如果設定這個參數，就無法定義 inline-config 或使用 Dockerfile 的參數。
• PATH_TO_INLINE_BUILD_CONFIG 是內嵌建構設定的路徑。如果觸發程序是指本機建構設定檔，請使用這個參數。如果設定這個參數，就無法定義 build-config 或使用 Dockerfile 的參數。
• DOCKERFILE 是 Dockerfile 的路徑。如果觸發程序參照 Dockerfile，請使用這個參數。如果您設定 Dockerfile 參數，就無法定義 build-config 或 inline-config。
• DOCKERFILE_DIR 是 Dockerfile 的目錄。
• DOCKERFILE_IMAGE 是 Cloud Build 建構的 Docker 映像檔名稱。
• 如要將觸發條件設為在分支版本上建構，BRANCH_NAME 是分支版本的名稱。如果設定這個參數，就無法定義 tag。
• TAG_NAME 是標記的名稱，如果您想將觸發條件設為根據標記建構，請輸入標記名稱。如果設定這個參數，就無法定義 branch。
• SUBSTITUTION (選用) 是要在建構規格中替換的參數。例如：_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'。
• FILTER (選用) 是觸發條件的 CEL 篩選運算式，例如 '_SUB_ONE == "prod"'。
• (選用) 如果指令中含有 --require-approval，Cloud Build 會要求手動核准觸發的建構作業。