Webhook トリガーの作成

Cloud Build では、着信 Webhook イベントの認証と受け入れができる Webhook トリガーを定義できます。これらのイベントをカスタム URL に送信すると、外部システムや具体的には Bitbucket.com、Bitbucket Server、GitLab などの外部 SCM を、イベントを介して Cloud Build に直接接続できます。カスタム統合や拡張コードを作成する必要もありません。

Webhook トリガーを使用すると、インライン ビルド構成ファイルを指定できるため、統合の設定を簡単にし、ビルドでの git クローン オペレーションを制御できます。

このページでは、Webhook トリガーを作成する方法について説明します。

始める前に

  • Cloud Build and Secret Manager API を有効にします。

    API を有効にする

API キーの取得

Webhook トリガーを作成する前に、受信 Webhook イベントを認証するための API キーが必要になります。

API キーを取得するには:

  1. Cloud Console で [認証情報] ページに移動します。

    [認証情報] ページを開く

  2. [認証情報を作成] をクリックします。

  3. [API キー] をクリックします。

    作成した API キーとともにポップアップ ボックスが表示されます。 このキーを使用するには、下記で説明するように、key=API_KEY をアプリケーションに渡します。

  4. キーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。

Webhook トリガーの作成

コンソール

Google Cloud Console を使用して Webhook トリガーを作成するには、以下の操作を行います。

  1. [トリガー] ページを開く

    [ビルドトリガー] ページを開く

  2. ページ上部でプロジェクトを選択し、[開く] をクリックします。

  3. [トリガーを作成] をクリックします。

  4. 次のトリガー設定を入力します。

    • 名前: トリガーの名前。
    • 説明(省略可): トリガーの説明。
    • イベント: [Webhook イベント] を選択して、受信 Webhook イベントにレスポンスしてビルドを開始するトリガーを設定します。
    • Webhook URL: 認証情報を入力後、以下の Webhook URL と、受信 Webhook イベントを認証するために最初に設定した API キーを使用します。

      • シークレット: 受信 Webhook イベントを認証するためのシークレットが必要になります。新しいシークレットを作成することも、既存のシークレットを使用することもできます。

        新しいシークレットを作成するには:

        1. [新規作成] をクリックします。
        2. [シークレットの作成] をクリックします。

          [Webhook シークレットの作成] ポップアップ ボックスが表示されます。

        3. [シークレット名] フィールドにシークレットの名前を入力します。

        4. [シークレットを作成] をクリックしてシークレットを保存します。クリックすると、シークレットが自動的に作成され Secret Manager に保存されます。

        既存の Secret を使用するには:

        1. [既存のものを使用] を選択します。
        2. [シークレット] フィールドで、使用するシークレットの名前をプルダウン メニューから選択するか、指示に従ってリソース ID でシークレットを追加します。
        3. [シークレットのバージョン] フィールドで、プルダウン メニューからシークレットのバージョンを選択します。

      シークレットを作成または選択すると、Webhook URL のプレビューが表示されます。この URL を使用して Webhook イベントを呼び出すには、POST メソッドを使用して HTTP リクエストを作成します。

       https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}
      

      これらの手順を完了すると、Secret Manager のシークレット アクセサーのロールが Cloud Build サービス アカウント service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com に自動的に付与されます。このロールがサービス アカウントに自動的に追加されない場合は、サービス アカウントに Secret Manager のロールを付与するで説明されている手順を実行してください。

    • ソース(省略可): Webhook トリガーの実行時にビルドするリポジトリを選択します。

    • [リビジョン](省略可): Webhook トリガーの実行時にビルドするブランチまたはタグを選択します。

      • ブランチ(省略可): このブランチ上でビルドするトリガーを設定します。リテラル値を指定する必要があります。正規表現は現在サポートされていません。
      • タグ(省略可): このタグでビルドするトリガーを設定します。リテラル値を指定する必要があります。正規表現は現在サポートされていません。
    • 構成: リモート リポジトリにあるビルド構成ファイルを選択するか、ビルドに使用するインライン ビルド構成ファイルを作成します。

      • タイプ: ビルドに使用する構成のタイプを選択します。
        • Cloud Build 構成ファイル(yaml または json): 構成にビルド構成ファイルを使用します。
        • Dockerfile: 構成に Dockerfile を使用します。
      • 場所: 構成の場所を指定します。

        • リポジトリ: 構成ファイルがリモート リポジトリにある場合は、ビルド構成ファイルの場所を指定するか、生成されたイメージの Dockerfile ディレクトリと名前を指定します。構成が Dockerfile の場合は、必要に応じてビルドのタイムアウトを指定できます。Dockerfile とイメージ名を指定すると、ビルドが実行される docker build コマンドのプレビューが表示されます。
        • インライン: 構成オプションとして Cloud Build 構成ファイル(yaml または json)を選択した場合、インライン ビルド構成を指定できます。Google Cloud Console で [エディタを開く] をクリックして、YAML または JSON 構文でビルド構成ファイルを書き込みます。[完了] をクリックしてビルド構成ファイルを保存します。

      次の例では、インライン ビルド構成ファイルのログに「hello world」とエコーされます。

       steps:
       - name: 'ubuntu'
         args: ['echo', 'hello world']
      
    • 置換(省略可): ビルド構成オプションとしてビルド構成ファイルを選択した場合、またはインライン ビルド構成ファイルを作成した場合、このフィールドを使用して、トリガー固有の置換変数を定義できます。置換変数の値を定義するときに、ペイロード バインディングを使用してデータを取得することもできます。

    • フィルタ(省略可): 置換変数に基づいてビルドを実行するかどうかを決定するルールをトリガー内に作成できます。

      Webhook トリガーに適用できるフィルタリングの構文の例については、CEL を使用したビルドイベントのフィルタリングをご覧ください。

  5. [作成] をクリックしてビルドトリガーを作成します。

gcloud

Webhook トリガーを作成するには、gcloud alpha コマンドを実行する必要があります。

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --subtitutions=\
         _SUB_ONE='$(body.message.test)', _SUB_TWO='$(body.message.output)'
       --filter='_SUB_ONE == prod'
       --build-config=PATH_TO_BUILD_CONFIG # or --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --tag=TAG_NAME  # or --branch=BRANCH_NAME

ここで

  • TRIGGER_NAME はトリガーの名前です。
  • PATH_TO_REPO は、ビルドを呼び出すリポジトリへのパスです。例: https://www.github.com/owner/repo
  • PATH_TO_SECRET は、Secret Manager に保存されているシークレットへのパスです。例: projects/my-project/secrets/my-secret/versions/2
  • PATH_TO_BUILD_CONFIG は、ビルド構成ファイルへのパスです。
  • PATH_TO_INLINE_BUILD_CONFIG は、インライン ビルド構成ファイルへのパスです。
  • TAG_NAME は、タグでビルドのトリガーを設定するタグの名前です。
  • BRANCH_NAME は、ブランチでビルドのトリガーを設定する場合、ブランチの名前です。

(省略可)サービス アカウントに Secret Manager のロールを付与する

Cloud Build は、Secret の構成中にそのロールがを必要とするサービス アカウントに Secret Manager のシークレット アクセサーのロールを自動的に付与します。このロールが必要なサービス アカウントに自動的に付与されない場合は、次の手順でロールを手動で追加し、サービス アカウントが Secret にアクセスできるようにします。

  1. Cloud Console で IAM ページを開きます。

    [IAM] ページを開く

  2. ロールを付与する Cloud Build サービス アカウントをメモします。

  3. Google Cloud Console で [Secret Manager] ページを開きます。

    [シークレット マネージャー] ページを開く

  4. Secret の名前をクリックします。

    [Secret の詳細] ページが表示されます。

    1. 右側にある情報パネルの [権限] タブをクリックします。

    2. [メンバーを追加] をクリックします。

    3. [新しいメンバー] セクションで、Cloud Build サービス アカウントに関連付けられているメンバーのメールアドレスを追加します。

    4. [ロールを選択] セクションで、[Secret Manager] > [Secret Manager シークレット アクセサー] を選択します。

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

次のステップ