Webhook トリガーの作成

Cloud Build では、着信 Webhook イベントの認証と受け入れができる Webhook トリガーを定義できます。これらのイベントはカスタム URL に送信されると、Bitbucket.com、Bitbucket Server、GitLab などの外部システムと外部ソースコード管理システムを Webhook イベントを介して Cloud Build に直接接続できます。

Webhook トリガーを使用すると、トリガーを作成するときにソースを指定せずにインライン ビルド構成ファイルを定義できます。インライン ビルド構成を使用すると、Git オペレーションを制御し、ビルドの残りの部分を定義できます。

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

始める前に

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

    API を有効にする

  • このページで gcloud コマンドを使用するために、Cloud SDK をインストールします。

Webhook トリガーの作成

コンソール

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

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

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

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

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

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

    • 名前: トリガーの名前。
    • 説明(省略可): トリガーの説明。
    • イベント: [Webhook イベント] を選択して、受信 Webhook イベントにレスポンスしてビルドを開始するトリガーを設定します。
    • Webhook URL: Webhook URL を使用して、受信 Webhook イベントを認証します。

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

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

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

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

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

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

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

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

        既存のシークレットを使用する場合は、Secret Manager のシークレット アクセサーのロールを Cloud Build サービス アカウント ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com に手動で付与する必要があります。詳しくは、サービス アカウントへの Secret Manager のロールの付与をご覧ください。

      シークレットを作成または選択すると、Webhook URL のプレビューが表示されます。URL には、Cloud Build によって生成された API キーとシークレットが含まれます。Cloud Build で API キーを取得できない場合は、手動で API キーを URL に追加するか、API キーの取得方法(API キーがない場合)をご覧ください。

      この URL を使用して POST メソッドで HTTP リクエストを行うことで、Webhook イベントを呼び出すことができます。

       curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"
      

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

    • ソース(省略可): Webhook トリガーの実行時にビルドするリポジトリを選択します。インライン ビルド構成を指定する場合は、次のソースを指定する必要はありません。

    • [リビジョン](省略可): Webhook トリガーの実行時にビルドするブランチまたはタグを選択します。 インライン ビルド構成を指定する場合は、次のリビジョンを指定する必要はありません。

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

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

        • リポジトリ: 構成ファイルがリモート リポジトリにある場合は、ビルド構成ファイルDockerfile ディレクトリの場所、または Bullpack のディレクトリを指定します。ビルド構成タイプが Dockerfile または buildpack の場合、ビルドするイメージの名前と、必要に応じてビルドのタイムアウトを指定する必要があります。Dockerfile または buildpack イメージ名を指定すると、ビルドが実行される docker build または pack コマンドのプレビューが表示されます。
        • buildpack の環境変数(省略可): 構成タイプとして buildpacks を選択した場合、[パック環境変数を追加] をクリックして buildpack 環境変数と値を指定します。buildpack 環境変数の詳細については、環境変数をご覧ください。
        • インライン: 構成オプションとして 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 builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --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_INLINE_BUILD_CONFIG は、--inline-config を使用する場合のインライン ビルド構成ファイルへのパスです。
  • TAG_NAME は、タグでビルドのトリガーを設定するタグの名前です。
  • --build-config を使用する場合は、PATH_TO_BUILD_CONFIG がビルド構成ファイルへのパスです。
  • BRANCH_NAME は、ブランチでビルドのトリガーを設定する場合、ブランチの名前です。

(省略可)API キーの取得

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

API キーを取得するには:

  1. Google Cloud Console の認証情報ページを開きます。

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

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

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

    作成した API キーとともにダイアログが表示されます。API キーをメモします。

  4. プロダクト アプリケーションのキーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。

    キーを制限する方法については、API キーの制限を適用するをご覧ください。

(省略可)サービス アカウントに 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. [New Principal] セクションで、Cloud Build サービス アカウントに関連付けられているメールを追加します。

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

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

CEL を使用したビルドイベントのフィルタリング

Cloud Build は、ビルドリソースにリストされているフィールドの変数 build で CEL を使用して、トリガー ID、イメージリスト、置換変数などのビルドイベントと関連するフィールドにアクセスします。filter 文字列を使用すると、Build リソースに表示されているフィールドを使用してビルド構成ファイル内のビルドイベントをフィルタリングできます。フィールドに関連付けられた正確な構文を見つけるには、cloudbuild.proto ファイルをご覧ください。

トリガー ID によるフィルタリング

トリガー ID でフィルタリングするには、build.build_trigger_id を使用してトリガー ID の値をfilter フィールドに指定します。ここで、trigger-id は文字列であるトリガー ID です。

filter: build.build_trigger_id == trigger-id

ステータスによるフィルタリング

ステータスでフィルタリングするには、build.status を使用して、フィルタリングするビルドのステータスを filter フィールドに指定します。

次の例は、filter フィールドを使用して SUCCESS ステータスのビルドイベントをフィルタリングする方法を示しています。

filter: build.status == Build.Status.SUCCESS

さまざまなステータスのビルドをフィルタリングすることもできます。次の例は、filter フィールドを使用して、ステータスが SUCCESSFAILURE、または TIMEOUT のビルドイベントをフィルタリングする方法を示しています。

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

フィルタリングできるその他のステータス値を確認するには、ビルドリソース リファレンスのステータスをご覧ください。

タグによるフィルタリング

タグでフィルタリングするには、build.tags を使用して filter フィールドにタグの値を指定します。ここで、tag-name はタグの名前です。

filter: tag-name in build.tags

size を使用すると、ビルドイベントで指定されたタグの数に基づいてフィルタリングできます。以下の例では、filter フィールドにより、1 つのタグが v1 に指定されたタグがちょうど 2 つあるビルドイベントがフィルタリングされます。

filter: size(build.tags) == 2 && "v1" in build.tags

画像によるフィルタリング

画像でフィルタリングするには、build.images を使用して filter フィールドに画像の値を指定します。ここで image-name は、gcr.io/example/image-one などの Container Registry にリストされる画像の完全な名前です。

filter: image-name in build.images

下の例では、filter が画像名として gcr.io/example/image-one または gcr.io/example/image-two が指定されているビルドイベントをフィルタリングします。

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

時間によるフィルタリング

filter フィールドに build.create_timebuild.start_timebuild.finish_time のいずれかのオプションを指定すると、ビルドの作成時間、開始時間、終了時間に基づいてビルドイベントをフィルタリングできます。

下の例では、filter フィールドで timestamp を使用し、ビルドを作成するリクエスト時刻を 2020 年 7 月 20 日 午前 6 時に指定して、ビルドイベントをフィルタリングします。

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

時刻の比較によりビルドイベントをフィルタリングすることもできます。下の例では、filter フィールドで timestamp を使用し、開始時刻を 2020 年 7 月 20 日午前 6 時と 2020 年 7 月 30 日午前 6 時の間に指定して、ビルドイベントをフィルタリングします。

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

CEL での時間帯の表記方法に関する詳細については、時間帯の言語の定義をご覧ください。

ビルド時間でフィルタリングするには、duration を使用してタイムスタンプを比較します。下の例では、filter フィールドで duration を使用して、ビルドが 5 分以上実行されるビルドイベントをフィルタリングします。

filter: build.finish_time - build.start_time >= duration("5m")

置換によるフィルタリング

build.substitutions を使用して filter フィールドに置換変数を指定すると、置換によってフィルタリングできます。次の例では、filter フィールドは置換変数 substitution-variable を含むビルドを一覧表示し、substitution-variable が指定された substitution-value と一致するかどうかを確認します。

filter: build.substitutions[substitution-variable] == substitution-value

ここで

  • substitution-variable は置換変数の名前です。
  • substitution-value は、置換値の名前です。

また、デフォルトの置換変数値でフィルタリングすることもできます。次の例では、filter フィールドにブランチ名が master のビルドとリポジトリ名が github.com/user/my-example-repo のビルドが一覧表示されます。デフォルトの置換変数 BRANCH_NAMEREPO_NAME がキーとして build.substitutions に渡されます。

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

正規表現を使用して文字列をフィルタリングする場合は、組み込みの matches 関数を使用できます。以下の例では、filter フィールドは、ステータスが FAILURE または TIMEOUT であり、正規表現 v{DIGIT}.{DIGIT}.{3 DIGITS}) と一致する値を持つビルド置換変数 TAG_NAME のあるビルドでフィルタリングします。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

デフォルトの置換値のリストについては、デフォルトの置換の使用をご覧ください。

次のステップ