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

第 1 代 第 2 代

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

使用 Webhook 觸發條件時，您可以指定內嵌建構設定，而非來源存放區。這項內嵌設定可讓您控管 Git 作業和建構工作流程。如要改為在存放區事件發生時自動建構，可以使用 Cloud Build 存放區觸發條件，直接與 GitHub 和 GitLab 等供應商整合。

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

本頁面概述如何建立 Webhook 觸發條件，以便自動建構來回應 Webhook 事件。

注意： 如要建立觸發條件，在存放區事件發生時自動執行建構作業，建議使用 Cloud Build 存放區觸發條件。使用 Cloud Build 存放區 (第 2 代) 的存放區觸發條件可透過程式輔助方式設定，並與原始碼供應商整合，包括支援 GitHub 和 GitLab。Cloud Build 存放區 (第 2 代) 也會使用 Secret Manager 代為管理驗證權杖和資訊。存放區觸發條件可讓您篩選傳入事件，並將建構狀態回傳給來源供應商，也可以設定為與私人網路搭配使用。詳情請參閱「存放區總覽」頁面。

事前準備

• 啟用 Cloud Build 和 Secret Manager API (如果尚未啟用)。

  啟用 API 所需的角色

  您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

  啟用 API

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

  注意： 如果您先前已安裝 gcloud CLI，請執行 gcloud components update，確認目前使用的是最新版本。

• 如果 Webhook 觸發條件使用 Cloud Build 存放區做為來源，請務必熟悉 Cloud Build 存放區。

建立 Webhook 觸發條件

控制台

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

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

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

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

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

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

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

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

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

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

   • 「Event」(事件)：選取「Webhook event」(Webhook 事件)，將觸發條件設為啟動建構作業，以回應傳入的 Webhook 事件。

   • Webhook 網址：使用 Webhook 網址驗證傳入的 Webhook 事件。您需要密鑰，才能驗證傳入的 Webhook 事件。您可以建立新密鑰或使用現有密鑰。這個密鑰與安全殼層金鑰相關聯的密鑰不同。

     建立 Secret 的步驟如下：

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

     2. 點選「建立密鑰」。

        系統會顯示「建立 Webhook 密鑰」對話方塊。

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

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

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

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

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

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

        建立或選取密鑰後，系統會顯示「Webhook URL preview」(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 代。

     • 「Repository」(存放區)：從可用存放區清單中，選取要建構的存放區。存放區的區域必須與觸發條件的區域相符。

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

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

       警告： 凡是有權讀取這個存放區的使用者，都能提交提取要求，並有可能藉此執行建構作業，部署透過提取要求提出的原始碼變更。如要防止這種行為，建議您採用手動核准功能，在有人對公開存放區發出提取要求時，針對建構作業進行把關。您也可以進一步瞭解觸發條件的建構階段權限。

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

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

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

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

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

       • Cloud Build 設定檔 (YAML 或 JSON)：使用建構設定檔進行設定。
       • Dockerfile：使用 Dockerfile 進行設定。
       • Buildpacks：使用 Buildpacks 進行設定。

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

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

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

         注意： Dockerfile 或 Buildpack 不支援內嵌建構設定。

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

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

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

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

5. 按一下「Create」(建立)，建立自動建構觸發條件。

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 名稱。
• 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 會要求手動核准觸發的建構作業。

叫用 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 角色授予服務帳戶

在建立 Webhook 觸發條件時設定密鑰，Cloud Build 通常會自動將 Secret Manager 密鑰存取者角色授予需要該角色的服務帳戶。不過，如果使用現有密鑰，您可能也需要手動將 Secret Manager 密鑰存取者角色授予 Cloud Build 服務帳戶：

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

   開啟 IAM 頁面

2. 選用：如要查看 Google 提供的帳戶，請勾選「Include Google-provided role grants」核取方塊。

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

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

   開啟「Secret Manager」頁面

5. 按一下密鑰名稱。

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

   1. 按一下「Permissions」(權限) 分頁標籤。

   2. 按一下「授予存取權」。

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

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

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

   5. 按一下 [儲存]。

(選用) 取得 API 金鑰

如要驗證傳入的 Webhook 事件，您需要 API 金鑰。這個 API 金鑰是您在設定 Webhook 觸發條件時選擇的密鑰的一部分。如果您還沒有 API 金鑰，或 Cloud Build 在 Google Cloud 控制台設定密鑰時無法擷取金鑰，可以手動建立 API 金鑰：

取得 API 金鑰的方法如下：

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

   開啟「憑證」頁面

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

3. 按一下「API 金鑰」。

   您會看到一個對話方塊，其中顯示已建立的 API 金鑰。記下 API 金鑰。

4. 如要限制金鑰用於產品應用程式，請按一下「Restrict key」(限制金鑰)，完成其他步驟來保護金鑰。否則，請按一下「關閉」。

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

後續步驟

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