Webhook を設定する

このページでは、Secure Source Manager で Webhook を設定する方法について説明します。

Webhook は、Secure Source Manager のイベントによってトリガーされ、ユーザーが指定した URL に送信される HTTP リクエストです。

始める前に

  1. Secure Source Manager インスタンスを作成します。
  2. Secure Source Manager リポジトリを作成する。

必要なロール

Webhook の作成に必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

Secure Source Manager のロールの付与については、IAM によるアクセス制御とユーザーにインスタンスへのアクセス権を付与するをご覧ください。

Webhook を設定する

コンソール

  1. Secure Source Manager ウェブ インターフェースで、Webhook を作成するリポジトリに移動します。
  2. [設定] をクリックします。
  3. [Webhook] をクリックし、[Webhook を追加] をクリックします。

  4. [フック ID] フィールドに、Webhook の ID を入力します。

  5. [ターゲット URL] フィールドに、Webhook URL を入力します。たとえば、Jenkins でビルドをトリガーする場合は、Webhook トリガーを設定してから、ここに Jenkins トリガー URL を入力して、Jenkins でビルドをトリガーできます。

  6. [トリガー] セクションで、次のいずれかを選択します。

    • Push: リポジトリへの push でトリガーします。
    • Pull request state changed: pull リクエストの状態が変更されたときにトリガーします。

  7. 機密性の高いクエリ文字列またはサービス アカウント認証を使用して、Webhook 認証を構成します。

    • 機密性の高いクエリ文字列:

      機密性の高いクエリ文字列は、Webhook URL の key 値と secret 値で構成され、key= 接頭辞と secret= 接頭辞が含まれます。機密性の高いクエリ文字列の認証を構成するには、Webhook URL からこれらの値を削除し、[機密性の高いクエリ文字列] フィールドに追加する必要があります。

      1. Webhook URL から ? を削除します。
      2. key= から始まる URL の残りの部分をコピーします。
      3. この部分を [機密性の高いクエリ文字列] フィールドに貼り付けます。
      4. Webhook URL から同じ部分を削除します。

      たとえば、次の URL があるとします。 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. [Push] を選択した場合は、[ブランチ フィルタ] フィールドに push イベントの許可リストを入力できます。

    [ブランチ フィルタ] フィールドでは glob パターンが使用され、一致するブランチに対するオペレーションのみがビルド トリガーを発生させます。たとえば、{main,dev} は main ブランチと dev ブランチへの push イベントでトリガーされます。フィールドが空または * の場合、すべてのブランチの push イベントが報告されます。構文については、glob のドキュメントをご覧ください。

  9. [Add webhook] をクリックします。

  10. Webhook が [Webhook] ページに表示されます。

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 URL の 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 の [Webhook] ページで、テストする Webhook をクリックします。

  2. ページの一番下までスクロールして、[テスト配信] をクリックします。

    プレースホルダ イベントが配信キューに追加されます。配信履歴に表示されるまで数秒かかることがあります。

  3. git コマンドを使用して、pull リクエストを push またはマージして、Webhook をテストすることもできます。

  4. Webhook トリガーを構成したサービスのビルド履歴で、トリガーされたビルドまたはイベントのステータスを確認します。

  5. 最初のテスト配信を送信すると、Secure Source Manager の Webhook ページの [最近の配信] セクションで、テスト配信のリクエストとレスポンスを確認することもできます。

Cloud Build YAML 変数をペイロード データに置き換える

ウェブフックを使用して Cloud Build に接続している場合は、Cloud Build YAML 変数を Secure Source Manager ウェブフック ペイロード データに置き換えることができます。

  1. Secure Source Manager の [Webhook] ページの [最近の配信] セクションで、最上行をクリックします。

    Webhook ペイロードによって送信されたリクエスト ヘッダーとコンテンツが表示されます。

  2. Cloud Build ダッシュボードに移動し、[トリガー] をクリックします。

  3. 設定するトリガーをクリックします。

  4. [詳細設定] セクションの [代入変数] で、[+ 変数を追加] をクリックします。

  5. 変数の名前と値を入力します。値の接頭辞は body です。

    たとえば、Cloud Build YAML で _REPO_URL をペイロード データ フィールド repository.clone_url に、_COMMIT_SHA を最新の commit 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}

次のステップ