連線到 Jenkins

您可以使用 Jenkins 觸發條件和 Secure Source Manager Webhook，啟動自動建構作業。

必要的角色

如要取得建立 Jenkins 建構觸發程序所需的權限，請要求管理員授予下列 IAM 角色：

Secure Source Manager 存放區管理員 (roles/securesourcemanager.repoAdmin) 存放區
Secure Source Manager 執行個體存取者 (roles/securesourcemanager.instanceAccessor) 在 Secure Source Manager 執行個體上

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

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

設定 Webhook 觸發條件

Jenkins 會使用建構觸發外掛程式啟用 CI/CD 自動化功能。您可以設定觸發條件來監聽傳入的事件，例如將新提交內容推送至存放區，或啟動提取要求，然後在傳入新事件時自動執行建構作業。您也可以設定觸發條件，讓系統在原始碼存放區發生任何變更時，或只有在變更符合特定條件時建構程式碼。

如要設定一般 Jenkins Webhook 觸發條件：

在 Jenkins 伺服器上安裝 Jenkins Git 外掛程式、SSH 憑證外掛程式和一般 Webhook 觸發外掛程式。
在 Jenkins 伺服器中產生有效的 SSH 金鑰組。 Secure Source Manager 僅支援 RSA 類型的金鑰。
執行下列指令，將 Secure Source Manager 執行個體網域新增至 Jenkins 伺服器 SSH known_hosts 檔案：
```
ssh -t git@INSTANCE_ID-INSTANCE_PROJECT_NUMBER-ssh.us-central1.sourcemanager.dev
```
其中：
- INSTANCE_ID 是 Secure Source Manager 執行個體的名稱。
- INSTANCE_PROJECT_NUMBER 是 Secure Source Manager 執行個體的專案號碼。如要瞭解專案編號的所在位置，請參閱「識別專案」。
舉例來說，下列指令會為專案編號為 123456789 的 prod-test-instance 執行個體新增執行個體網域。
```
ssh -t git@prod-test-instance-123456789-ssh.us-central1.sourcemanager.dev
```
回覆 yes，將執行個體網域新增至已知主機清單。
在 Jenkins 的「Manage Credentials」(管理憑證) 頁面中：
1. 選取「SSH username with private key」。
2. 貼上 Jenkins 伺服器 SSH 私密金鑰。
3. 在「類型」下拉式選單中，視需要填寫其他欄位。
點選「建立」。
在 Jenkins 網頁介面中，建立新的 Jenkins 工作。
在 Jenkins 工作設定頁面的「Source Code Management」專區下方，選取「Git」。
在「Git」部分，將 Secure Source Manager 存放區 SSH 網址貼為存放區網址，輸入建構分支 (例如 */main)，然後選取您先前在「管理憑證」頁面中新增的已儲存私密 SSH 金鑰憑證。
在「建構作業觸發條件」部分，選取「一般 Webhook 觸發條件」。

您也可以選擇新增權杖，這樣只有在叫用時提供該權杖，工作才會觸發。如要新增權杖，請在「Generic Webhook Trigger」部分下方的「Token」欄位中輸入權杖。
在「Build」(建構) 區段中，提供您要用於這項 Jenkins 工作的建構指令碼。舉例來說，您可以執行 cat README.md 來列印 README.md 的內容。
按一下「儲存」即可建立 Jenkins 工作。

設定服務帳戶並授予必要權限

如果您沒有要使用的服務帳戶，請建立服務帳戶。

請確認您具備服務帳戶的 iam.serviceAccounts.actAs 權限。這項權限是服務帳戶使用者 (roles/iam.serviceAccountUser) 角色的一部分。
在 Secure Source Manager 網頁介面中，按一下「更多選項」選單。
按一下「服務帳戶 SSH 金鑰」。系統會開啟「服務帳戶 SSH 金鑰」頁面，並顯示您新增的現有金鑰清單。
按一下「Add key」。
在「新增 SSH 金鑰」頁面中，輸入金鑰的下列值：
1. 服務帳戶：要搭配使用 SSH 金鑰的服務帳戶電子郵件，格式為 SA_NAME@PROJECT_ID.iam.gserviceaccount.com
  
  地點
  - SA_NAME 是服務帳戶名稱。
  - PROJECT_ID 是建立服務帳戶的專案 ID。
2. 安全殼層公開金鑰：您的 Jenkins 公開安全殼層金鑰。

授予 Secure Source Manager 服務代理權限

如果服務帳戶與 Secure Source Manager 執行個體不在同一個專案中，您也必須授予 Secure Source Manager 服務代理程式「服務帳戶憑證建立者」(roles/iam.serviceAccountTokenCreator) 角色或 iam.serviceAccounts.signJwt 權限。

如果服務帳戶與 Secure Source Manager 執行個體位於同一個專案，請跳至「授予服務帳戶存放區角色」。

執行下列指令，取得服務帳戶的現有 IAM 政策：
```
gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
    --format json
```
其中 SERVICE_ACCOUNT 是您要使用的服務帳戶。帳戶格式應為數字服務帳戶 ID 或電子郵件地址，例如 123456789876543212345 或 my-iam-account@somedomain.com。

輸出內容會包含所有現有繫結，如果沒有任何繫結，則會包含類似下列內容的 etag 值：
```
{
"etag": "BwUjHYKJUiQ="
}
```
重要事項：請保留 get-iam-policy 回應中的 etag 值，確保您不會覆寫他人的政策變更。如要覆寫所有其他變更，可以移除 etag 值。
將輸出內容複製到名為 policy.json 的新檔案。
如要授予 Secure Source Manager 服務代理程式「服務帳戶憑證建立者」角色 (roles/iam.ServiceAccountTokenCreator)，請修改 policy.json，新增下列項目：
```
{
    "role": "roles/iam.serviceAccountTokenCreator",
    "members": [
        "serviceAccount:service-INSTANCE_PROJECT_NUMBER@gcp-sa-sourcemanager.iam.gserviceaccount.com"
    ]
}
```
其中 INSTANCE_PROJECT_NUMBER 是 Secure Source Manager 執行個體的專案號碼。
執行下列指令，取代服務帳戶現有的 IAM 政策：
```
gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
```
更改下列內容：
- SERVICE_ACCOUNT，並提供服務帳戶 ID 或電子郵件地址。
- POLICY_FILE，並提供包含新政策的 JSON 格式檔案位置和名稱。

授予服務帳戶存放區角色

在 Secure Source Manager 網頁介面中，前往要授予服務帳戶權限的存放區。
按一下「Permissions」(權限) 分頁標籤。
按一下「新增使用者」。
在「新增主體」欄位中，輸入服務帳戶的電子郵件地址。
在「角色」下拉式選單中，選取「Secure Source Manager Repository Reader」(Secure Source Manager 存放區讀取者)。
執行下列指令，將 securesourcemanager.instanceAccessor 角色指派給服務帳戶：
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SA_EMAIL \
    --role=roles/securesourcemanager.instanceAccessor
```
更改下列內容：
- 將 PROJECT_ID 替換為 Secure Source Manager 執行個體專案 ID。
- SA_EMAIL 替換為服務帳戶電子郵件地址。

設定 Webhook

在 Secure Source Manager 網頁介面中，前往要建立 Webhook 的存放區。
按一下「設定」。
按一下「Webhook」，然後按一下「新增 Webhook」。
在「Hook ID」(Webhook ID) 欄位中，輸入 Webhook 的 ID。

注意： Hook ID 必須遵循資源命名慣例。只能包含小寫英文字母、數字或破折號，開頭必須是英文字母，且建立 Webhook 後無法變更。
在「Target URL」(目標網址) 欄位中，輸入 Jenkins 觸發網址。
如果您在設定 Jenkins 觸發程序時使用了選用權杖，Jenkins 觸發程序網址的結尾就會包含該權杖。為避免權杖外洩，請從目標網址尾端移除權杖，然後複製到「敏感查詢字串」欄位。

如要在觸發網址中找出權杖，請尋找以 token= 開頭的文字。

舉例來說，如果您的網址類似以下內容： https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

從「目標網址」欄位中，複製並移除以問號開頭的部分。?token=jenkins-job1然後移除開頭的問號，將剩餘部分 token=jenkins-job1 移至「Sensitive Query String」(機密查詢字串) 欄位。
在「觸發條件」部分，選取下列其中一個選項：
- 推送：在推送至存放區時觸發。
- 提取要求狀態已變更：在提取要求狀態變更時觸發。
如果您選取「推送」，則可以在「分支版本篩選器」欄位中，輸入推送事件的允許清單。

「Branch filter」(分支篩選器) 欄位會使用 glob 模式，只有在相符分支上執行的作業才會觸發建構。如果欄位空白或為 *，系統就會回報所有分支機構的推播事件。
按一下 [Add Webhook]。
Webhook 會顯示在「Webhooks」頁面。

注意： 新增或編輯 Webhook 時，Sensitive Query String 的長度可能與輸入的長度不一致，這是正常現象，因為系統會使用預留位置字串來確保安全性。

測試 Webhook

在 Secure Source Manager 的「Webhooks」(Webhook) 頁面中，按一下要測試的 Webhook。
前往頁面底部，然後按一下「測試傳送」。

系統會將虛假事件加入傳送佇列。可能需要幾秒鐘才會顯示在運送記錄中。
您也可以使用 git 指令推送或合併提取要求，測試 Webhook。
在 Jenkins 專案中，查看「Build History」(建構記錄) 中由測試事件觸發的建構作業。
傳送第一筆測試傳送內容後，您也可以在安全來源管理工具網頁的「近期傳送內容」部分，查看測試傳送內容的「要求」和「回應」。

後續步驟

參閱 Jenkins 說明文件。