連線到 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 觸發條件：

1. 在 Jenkins 伺服器上安裝 Jenkins Git 外掛程式、SSH 憑證外掛程式和一般 Webhook 觸發外掛程式。

2. 在 Jenkins 伺服器中產生有效的 SSH 金鑰組。 Secure Source Manager 僅支援 RSA 類型的金鑰。

3. 執行下列指令，將 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 [e-mail]
   

   回覆 yes，將執行個體網域新增至已知主機清單。

4. 在 Jenkins 的「Manage Credentials」(管理憑證) 頁面中：

   1. 選取「SSH username with private key」。
   2. 貼上 Jenkins 伺服器 SSH 私密金鑰。
   3. 在「類型」下拉式選單中，視需要填寫其他欄位。

5. 點選「建立」。

6. 在 Jenkins 網頁介面中，建立新的 Jenkins 工作。

7. 在 Jenkins 工作設定頁面的「Source Code Management」部分，選取「Git」。

8. 在「Git」部分，將 Secure Source Manager 存放區 SSH 網址貼為存放區網址，輸入建構分支 (例如 */main)，然後選取您先前在「管理憑證」頁面中新增的已儲存私密 SSH 金鑰憑證。

9. 在「建構觸發條件」部分，選取「一般 Webhook 觸發條件」。

   您也可以選擇新增權杖，這樣只有在叫用時提供該權杖，才會觸發工作。如要新增權杖，請在「Generic Webhook Trigger」部分下方的「Token」欄位中輸入權杖。

10. 在「Build」(建構) 區段中，提供您要用於這項 Jenkins 工作的建構指令碼。舉例來說，您可以執行 cat README.md 來列印 README.md 的內容。

11. 按一下「儲存」，即可建立 Jenkins 工作。

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

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

   請確認您具備服務帳戶的 iam.serviceAccounts.actAs 權限。這項權限屬於「服務帳戶使用者」roles/iam.serviceAccountUser角色。

2. 在 Secure Source Manager 網頁介面中，按一下「更多選項」選單。

3. 按一下「服務帳戶 SSH 金鑰」。系統會開啟「服務帳戶 SSH 金鑰」頁面，並顯示您新增的現有金鑰清單。

4. 按一下「Add key」。

5. 在「新增安全殼層金鑰」頁面中，輸入金鑰的下列值：

   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 執行個體位於同一個專案，請跳至「授予服務帳戶存放區角色」。

1. 執行下列指令，取得服務帳戶的現有 IAM 政策：

   gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT \
       --format json
   

   其中 SERVICE_ACCOUNT 是您要使用的服務帳戶。 帳戶格式應為數字服務帳戶 ID 或電子郵件地址，例如 123456789876543212345 或 [e-mail]。

   輸出內容會包含所有現有繫結，如果沒有任何繫結，則會包含類似下列內容的 etag 值：

   {
   "etag": "BwUjHYKJUiQ="
   }
   

   重要事項： 請保留 get-iam-policy 回應中的 etag 值，確保您不會覆寫他人的政策變更。如要覆寫所有其他變更，可以移除 etag 值。

2. 將輸出內容複製到名為 policy.json 的新檔案。

3. 如要授予 Secure Source Manager 服務代理程式「服務帳戶憑證建立者」角色 (roles/iam.ServiceAccountTokenCreator)，請修改 policy.json，新增下列項目：

   {
       "role": "roles/iam.serviceAccountTokenCreator",
       "members": [
           "serviceAccount:[e-mail]"
       ]
   }
   

   其中 INSTANCE_PROJECT_NUMBER 是 Secure Source Manager 執行個體的專案號碼。

4. 執行下列指令，替換服務帳戶的現有 IAM 政策：

   gcloud iam service-accounts set-iam-policy SERVICE_ACCOUNT POLICY_FILE
   

   更改下列內容：

   • SERVICE_ACCOUNT，並提供服務帳戶 ID 或電子郵件地址。
   • POLICY_FILE，並提供包含新政策的 JSON 格式檔案位置和名稱。

授予服務帳戶存放區角色

1. 在 Secure Source Manager 網頁介面中，前往要授予服務帳戶權限的存放區。
2. 按一下「Permissions」(權限) 分頁標籤。
3. 按一下「新增使用者」。
4. 在「新增主體」欄位中，輸入服務帳戶的電子郵件地址。
5. 在「Role」(角色) 下拉式選單中，選取「Secure Source Manager Repository Reader」(安全來源管理員存放區讀者)。

6. 執行下列指令，將 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

1. 在 Secure Source Manager 網頁介面中，前往要建立 Webhook 的存放區。
2. 按一下「設定」。
3. 按一下「Webhook」，然後按一下「新增 Webhook」。

4. 在「Hook ID」(Webhook ID) 欄位中，輸入 Webhook 的 ID。

   注意： Hook ID 必須遵循資源命名慣例。只能包含小寫英文字母、數字或破折號，開頭必須是英文字母，且建立 Webhook 後無法變更。

5. 在「目標網址」欄位中，輸入 Jenkins 觸發網址。

6. 如果您在設定 Jenkins 觸發程序時使用了選用權杖，Jenkins 觸發程序網址的結尾就會包含該權杖。為避免權杖外洩，請從目標網址結尾移除權杖，然後複製到「敏感查詢字串」欄位。

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

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

   從「目標網址」欄位中，複製並移除以問號開頭的部分。?token=jenkins-job1然後移除開頭的問號，將剩餘部分 token=jenkins-job1 移至「Sensitive Query String」(機密查詢字串) 欄位。

7. 在「觸發條件」部分，選取下列其中一個選項：

   • 推送：在推送至存放區時觸發。
   • 提取要求狀態已變更：在提取要求狀態變更時觸發。

8. 如果您選取「推送」，則可以在「分支版本篩選器」欄位中，輸入推送事件的允許清單。

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

9. 按一下 [Add Webhook]。

10. Webhook 會顯示在「Webhooks」頁面。

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

測試 Webhook

1. 在 Secure Source Manager 的「Webhooks」(Webhook) 頁面中，按一下要測試的 Webhook。

2. 前往頁面底部，然後按一下「測試傳送」。

   系統會將虛假事件加入傳送佇列。系統可能需要幾秒鐘才會在運送記錄中顯示。

3. 您也可以使用 git 指令推送或合併提取要求，測試 Webhook。

4. 在 Jenkins 專案中，查看「Build History」(建構記錄) 中由測試事件觸發的建構作業。

5. 傳送第一筆測試遞送後，您也可以在安全來源管理工具網頁的「近期遞送」部分，查看測試遞送的「要求」和「回應」。

後續步驟

• 參閱 Jenkins 說明文件。