本頁面由 Cloud Translation API 翻譯而成。

連結至 Cloud Build

本頁詳細說明如何使用 Cloud Build 設定檔和 Secure Source Manager 存放區中的觸發條件 YAML 檔案，從 Secure Source Manager 自動叫用建構作業。

事前準備

必要的角色

如要取得將 Secure Source Manager 存放區連結至 Cloud Build 的必要權限，請要求管理員授予下列 IAM 角色：

Secure Source Manager 存放區寫入者 (roles/securesourcemanager.repoWriter) 存放區
Secure Source Manager 執行個體存取者 (roles/securesourcemanager.instanceAccessor) 在 Secure Source Manager 執行個體上

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

如要瞭解如何授予 Secure Source Manager 角色，請參閱「使用 IAM 控管存取權」和「授予使用者執行個體存取權」。

必要服務帳戶角色

如要建立建構作業及從 Cloud Build 取得建構作業狀態，請將下列 Identity and Access Management (IAM) 角色授予 Secure Source Manager 服務代理程式 (service-PROJECT-NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com)：

在啟用 Cloud Build 的專案中，您必須擁有 Cloud Build 編輯者角色 (roles/cloudbuild.builds.editor)。
Cloud Build 服務帳戶的服務帳戶使用者角色 (roles/iam.serviceAccountUser)，或建立 Cloud Build 服務帳戶的專案。
如果啟用 Cloud Build 的專案與啟用 Secure Source Manager 的專案不同，請在 Cloud Build 專案中授予「Service Usage Consumer」角色 (roles/serviceusage.serviceUsageConsumer)。
如果建構作業是在工作站集區中執行，請在 Cloud Build 專案中，將 Cloud Build WorkerPool User 角色 (roles/cloudbuild.workerPoolUser) 授予 Secure Source Manager 服務帳戶。

如要讓 Cloud Build 從 Secure Source Manager 存放區讀取資料，請將下列 IAM 角色授予 Cloud Build 服務帳戶：

Secure Source Manager 執行個體的「Secure Source Manager 執行個體存取者」角色 (roles/securesourcemanager.instanceAccessor)。
您要連結至 Cloud Build 的 Secure Source Manager 存放區，必須具備Secure Source Manager 存放區讀取者角色。

視您的用途而定，Cloud Build 服務帳戶可能需要額外的 IAM 角色才能執行建構作業，例如：

如要在 Cloud Logging 中儲存建構記錄，請將「記錄寫入者」角色授予 Cloud Build 服務帳戶。
如要存取 Secret Manager 中的密鑰，請將 Secret Manager 密鑰存取者 (roles/secretmanager.secretAccessor) 角色授予 Cloud Build 服務帳戶。

如要瞭解如何將 IAM 角色授予服務代理程式，請參閱授予或撤銷單一角色。

如要瞭解建構記錄，請參閱「設定建構記錄」。

建立建構設定檔

建構設定檔定義 Cloud Build 執行建構工作所需的欄位。您可以使用 YAML 語法編寫建構設定檔。

您可以在要建構的分支中建立建構設定檔。

如要建立建構設定檔，請按照下列步驟操作：

在 Secure Source Manager 網頁介面中，選取要連結至 Cloud Build 的存放區。
選取要使用 Cloud Build 建構的分支。
建立建構設定檔。如要瞭解如何建立建構設定檔，請按照「建立建構設定檔」一文中的操作說明進行。
將變更內容提交至分支版本。

建立觸發條件檔案

觸發條件設定檔必須在存放區的預設分支中建立。

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

在本機存放區或 Secure Source Manager 網頁介面中，切換至預設分支版本。
建立名為 .cloudbuild/triggers.yaml 的檔案。
在 .cloudbuild/triggers.yaml 檔案中設定觸發條件：
```
triggers:
- name: TRIGGER_NAME
  project: PROJECT_ID
  configFilePath: CLOUD_BUILD_CONFIG_PATH
  eventType: EVENT_TYPE
  ignoredGitRefs: IGNORED_GIT_REFS
  includedGitRefs: INCLUDED_GIT_REFS
  serviceAccount: SERVICE_ACCOUNT
  includedFiles: INCLUDED_FILES
  ignoredFiles: IGNORED_FILES
  disabled: DISABLED_BOOL
  substitutions:
    _VARIABLE_NAME: VARIABLE_VALUE
    OVERRIDE_VARIABLE_NAME: OVERRIDE_VARIABLE_VALUE
```
更改下列內容：
- TRIGGER_NAME，並為觸發條件命名。觸發條件名稱只能包含英數字元和破折號，且開頭或結尾不得為破折號。觸發條件名稱長度不得超過 64 個字元。
- PROJECT_ID 替換為啟用 Cloud Build 的專案 ID。 Google Cloud 這是選填欄位。預設為 Secure Source Manager 專案。
- CLOUD_BUILD_CONFIG_PATH，並提供要用於此觸發程序的 Cloud Build 設定檔路徑。這是選填欄位。預設值為 .cloudbuild/cloudbuild.yaml
- EVENT_TYPE，並選取要觸發建構作業的事件類型。選項如下：
  - push，在推送至指定分支版本時觸發
  - pull_request，在提取要求傳送至指定分支時觸發
  這是選填欄位。預設值為 push。
- INCLUDED_GIT_REFS，並可選擇性使用符合 Git 參照的 RE2 規則運算式格式，觸發建構作業。預設值為空白。如果值為空白，表示沒有限制。
- IGNORED_GIT_REFS，並使用 RE2 規則運算式格式 (選用) 搭配規則運算式，比對您不想觸發建構作業的 Git 參照。預設值為空白。如果值為空白，表示沒有限制。系統會先檢查 ignoredGitRefs 欄位，再檢查 includedGitRefs 欄位。如要進一步瞭解這些欄位，請參閱觸發條件檔案結構定義。
- SERVICE_ACCOUNT，並以 projects/PROJECT_ID/serviceAccounts/ACCOUNT 格式提供要用於建構作業的 Cloud Build 服務帳戶。將 ACCOUNT 替換為服務帳戶的電子郵件地址或專屬 ID。最佳做法是設定使用者指定的服務帳戶。由於舊版 Cloud Build 服務帳戶有限制，因此無法使用。
- INCLUDED_FILES，並視需要使用 RE2 格式的規則運算式，比對要觸發建構的檔案。
  
  如果變更的檔案不符合 ignoredFiles 篩選器欄位，但符合 includedFiles 篩選器欄位，系統就會觸發建構。預設值為空白。如果值為空白，表示沒有限制。
- IGNORED_FILES，並視需要使用 RE2 格式的規則運算式，比對您不想觸發建構的檔案。
  
  如果修訂中的所有變更檔案都符合這個篩選器欄位，系統就不會觸發建構。預設值為空白。如果值為空白，表示沒有任何限制。
- DISABLED_BOOL，然後按一下 true 停用觸發條件，或按一下 false 啟用觸發條件。這是選填欄位。預設值為 false。
- VARIABLE_NAME，並在觸發條件檔案中導入變數。
- VARIABLE_VALUE，並將變數值設為該值。
- OVERRIDE_VARIABLE_NAME，這是 Secure Source Manager 的預設替代變數名稱。如要瞭解可用的預設替代變數，請參閱「觸發條件檔案結構定義」的替代部分。
- OVERRIDE_VARIABLE_VALUE，並將預設替代變數的預設值覆寫為您要的值。
將觸發條件設定檔提交至預設分支版本。

觸發條件檔案提交後，Secure Source Manager 會根據觸發條件檔案中的設定觸發建構作業。

Secure Source Manager 會讀取下列類型事件的設定檔和相關聯的修訂版本 SHA 或 Git 參照：
- 如果是 push 事件，Secure Source Manager 會在推送完成時讀取提交 SHA 或 Git 參照。
- 如果是 pull_request 事件，Secure Source Manager 會在提取提取要求變更時，讀取提交 SHA 或 Git 參照。

查看建構狀態

如果建構作業是由推送或提取要求事件觸發，Secure Source Manager 網頁介面會顯示提交和建構狀態。

建構狀態可能的值如下：

SUCCESS：建構作業已順利完成。
警告：嘗試建構時發生問題。
失敗：建構作業在執行期間失敗。

如果設定分支保護規則，要求觸發程序檔案中設定的觸發程序通過狀態檢查，即可防止建構失敗的提交內容合併至重要分支。如要進一步瞭解分支保護功能，請參閱「分支保護總覽」。

如要查看推送事件的建構狀態，請按照下列步驟操作：

在 Secure Source Manager 網頁介面中，前往存放區。

如果最新的推送事件觸發了建構作業，狀態會顯示在修訂版本 SHA 旁邊。如要查看該狀態的詳細資料，請按一下狀態。
如要查看先前修訂版本的建構狀態，請選取「修訂版本」，查看修訂版本記錄，然後按一下要查看詳細資料的狀態。

如要查看提取要求事件的建構狀態，請按照下列步驟操作：

在 Secure Source Manager 網頁介面中，按一下「提取要求」。
按一下要查看的提取要求。

如果建構作業是由提取要求觸發，您會看到名為「所有檢查都成功」或「部分檢查回報警告」的部分。

疑難排解

如要瞭解如何診斷及解決與 Secure Source Manager 連線時發生的 Cloud Build 錯誤，請參閱「觸發條件檔案未觸發建構」。

後續步驟

瞭解如何在 Cloud Build 中查看建構結果。
瞭解如何排解建構錯誤。

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