設定 Webhook

本頁說明如何在 Secure Source Manager 中設定 Webhook。

Webhook 是由 Secure Source Manager 中的事件觸發的 HTTP 要求，並傳送至使用者指定的網址。

事前準備

  1. 建立 Secure Source Manager 執行個體。
  2. 建立 Secure Source Manager 存放區。

必要的角色

如要取得建立 Webhook 所需的權限，請要求管理員授予您下列 IAM 角色：

  • 使用機密查詢字串驗證 Webhook：
    • Secure Source Manager 存放區管理員 (roles/securesourcemanager.repoAdmin) Secure Source Manager 存放區
    • Secure Source Manager 執行個體存取者 (roles/securesourcemanager.instanceAccessor) Secure Source Manager 執行個體
  • 使用服務帳戶授權驗證 Webhook：

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

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

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

設定 Webhook

控制台

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

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

  5. 在「目標網址」欄位中，輸入 Webhook 網址。舉例來說，如要在 Jenkins 中觸發建構作業，可以設定 Webhook 觸發條件，然後在此輸入 Jenkins 觸發網址，即可在 Jenkins 中觸發建構作業。

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

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

  7. 使用私密查詢字串或服務帳戶驗證，設定 Webhook 驗證：

    • 敏感查詢字串：

      敏感查詢字串包含來自 Webhook 網址的 key 和 secret 值，包括 key= 和 secret= 前置字元。如要設定私密查詢字串授權，請從 Webhook 網址移除這些值，然後新增至「私密查詢字串」欄位：

      1. 從 Webhook 網址中刪除 ?。
      2. 複製網址的其餘部分，從 key= 開始。
      3. 將這部分貼入「敏感查詢字串」欄位。
      4. 從 Webhook 網址中刪除相同部分。

      舉例來說，假設有以下網址： https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

      您的機密查詢字串如下： key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=My%20Secret%20

    • 服務帳戶驗證：

      1. 確認存放區的服務帳戶已具備「必要角色」中定義的 IAM 角色，可進行服務帳戶驗證。
      2. 選取「啟用服務帳戶驗證」。

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

    「Branch filter」(分支篩選器) 欄位會使用 glob 模式，且只有在相符分支上執行的作業才會觸發建構。舉例來說，{main,dev} 會在推送事件觸發時，將事件推送至 main 和 dev 分支。如果該欄位空白或為 *，系統會回報所有分支機構的推播事件。如要瞭解語法，請參閱 glob 說明文件。

  9. 按一下 [Add Webhook]。

  10. 網頁掛鉤會顯示在「Webhooks」頁面。

REST

如要建立 Webhook，請對 hooks 端點發出 POST 要求，叫用 hooks.create 方法。您可以使用私密查詢字串或服務帳戶驗證，驗證 Webhook。

  • 敏感查詢字串

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook?key=${KEY}&secret=${SECRET}",
    "events": ["PUSH"]
    "sensitiveQueryString": "${SENSITIVE_QUERY_STRING_VALUE}"
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

    你的 SENSITIVE_QUERY_STRING_VALUE 應為 webhook 網址中的 key 和 secret 值。舉例來說，如果 key 為 eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf，且 secret 為 MySecret，則 SENSITIVE_QUERY_STRING_VALUE 應為 key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=MySecret。

  • 服務帳戶驗證

    curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUri": "https://${SERVICE_NAME}.app/webhook",
    "events": ["PUSH"],
    "serviceAccountAuth": true
  }' \
  "https://securesourcemanager.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/repositories/${REPOSITORY}/hooks?hook_id=${HOOK_ID}"

測試 Webhook

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

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

    系統會將預留位置活動新增至遞送佇列。可能需要幾秒鐘，才會顯示在運送記錄中。

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

  4. 在設定 Webhook 觸發條件的服務中，查看觸發的建構作業或事件在建構作業記錄中的狀態。

  5. 傳送第一筆測試交付內容後，您也可以在 Secure Source Manager 的 Webhook 頁面「近期交付內容」部分，查看測試交付內容的「要求」和「回應」。

以酬載資料取代 Cloud Build YAML 變數

如果您使用 Webhook 連線至 Cloud Build，可以將 Cloud Build YAML 變數替換為 Secure Source Manager Webhook 酬載資料。

  1. 在 Secure Source Manager 的「Webhook」頁面中，點選「近期傳送」部分中的頂端資料列。

    系統會顯示 Webhook 酬載傳送的「要求」標頭和內容。

  2. 前往 Cloud Build 資訊主頁，然後點選「觸發條件」。

  3. 按一下要設定的觸發條件。

  4. 在「進階」部分的「替代變數」下方，按一下「+ 新增變數」。

  5. 輸入變數的名稱和值。值前置字元為 body。

    舉例來說，如要將 _REPO_URL 替換為酬載資料欄位 repository.clone_url，並將 _COMMIT_SHA 替換為 Cloud Build YAML 中的最新提交 SHA，請輸入下列名稱和值：

    • 變數 1：_REPO_URL 值 1：$(body.repository.clone_url)
    • 變數 2：_COMMIT_SHA 值 2：$(body.after)

    Cloud Build YAML 檔案類似於下列內容：

    steps:
- name: gcr.io/cloud-builders/git
  env:
  - '_REPO_URL=$_REPO_URL'
  - '_COMMIT_SHA=$_COMMIT_SHA'
  script: |
    #!/bin/sh
    git clone ${_REPO_URL} /workspace
    cd /workspace
    git reset --hard ${_COMMIT_SHA}

後續步驟