Cloud Build では、着信 Webhook イベントの認証と受け入れができる Webhook トリガーを定義できます。これらのイベントはカスタム URL に送信されると、Bitbucket.com、Bitbucket Server、GitLab などの外部システムと外部ソースコード管理システムを Webhook イベントを介して Cloud Build に直接接続できます。
Webhook トリガーを使用すると、トリガーを作成するときにソースを指定せずにインライン ビルド構成ファイルを定義できます。インライン ビルド構成を使用すると、Git オペレーションを制御し、ビルドの残りの部分を定義できます。
このページでは、Webhook イベントに応じてビルドを自動化する Webhook トリガーを作成する方法について説明します。
準備
-
Cloud Build and Secret Manager API を有効にします。
このページで
gcloudコマンドを使用するには、Google Cloud CLI をインストールします。
Webhook トリガーの作成
コンソール
Google Cloud Console を使用して Webhook トリガーを作成するには、以下の操作を行います。
[トリガー] ページを開く
ページ上部でプロジェクトを選択し、[開く] をクリックします。
[トリガーを作成] をクリックします。
次のトリガー設定を入力します。
- 名前: トリガーの名前。
リージョン: トリガーのリージョンを選択します。
- リージョンとしてグローバルを選択した場合、Cloud Build はビルドを実行するためにデフォルトのプールを使用します。
- 非グローバル リージョンを選択して、トリガーに関連付けられたビルド構成ファイルでプライベート プールを指定すると、Cloud Build はプライベート プールを使用してビルドを実行します。この場合、トリガーで指定するリージョンは、プライベート プールを作成したリージョンと一致する必要があります。
- 非グローバル リージョンを選択し、トリガーに関連付けられたビルド構成ファイルでプライベート プールが指定されていない場合、Cloud Build はデフォルトのプールを使用してトリガーと同じリージョンでビルドを実行します。
説明（省略可）: トリガーの説明。
イベント: [Webhook イベント] を選択して、受信 Webhook イベントにレスポンスしてビルドを開始するトリガーを設定します。
Webhook URL: Webhook URL を使用して、受信 Webhook イベントを認証します。
シークレット: 受信 Webhook イベントを認証するためのシークレットが必要になります。新しいシークレットを作成することも、既存のシークレットを使用することもできます。 このシークレットは SSH 認証鍵に関連付けられたシークレットとは別のものです。
新しいシークレットを作成するには:
- [新規作成] をクリックします。
[シークレットの作成] をクリックします。
[Webhook シークレットの作成] ポップアップ ボックスが表示されます。
[シークレット名] フィールドにシークレットの名前を入力します。
[シークレットを作成] をクリックしてシークレットを保存します。クリックすると、シークレットが自動的に作成され Secret Manager に保存されます。
既存の Secret を使用するには:
- [既存のものを使用] を選択します。
- [シークレット] フィールドで、使用するシークレットの名前をプルダウン メニューから選択するか、指示に従ってリソース ID でシークレットを追加します。
- [シークレットのバージョン] フィールドで、プルダウン メニューからシークレットのバージョンを選択します。
既存のシークレットを使用する場合は、Secret Manager のシークレット アクセサーのロールを Cloud Build サービス アカウント
service-${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 イベントを呼び出すことができます。
リージョンとしてグローバルを選択した場合、Webhook イベントを呼び出すには、次のコマンドを使用します。
curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"us-central1などの非グローバルなリージョンを選択する場合は、次のコマンドを使用して Webhook イベントを呼び出します。curl -X POST -H "application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}&trigger=${TRIGGER_NAME}&projectId=${PROJECT_ID}" -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 を使用したビルドイベントのフィルタリングをご覧ください。
[作成] をクリックしてビルドトリガーを作成します。
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 キーを取得するには:
Google Cloud Console の認証情報ページを開きます。
[認証情報を作成] をクリックします。
[API キー] をクリックします。
作成した API キーとともにダイアログが表示されます。API キーをメモします。
プロダクト アプリケーションのキーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。
キーを制限する方法については、API キーの制限を適用するをご覧ください。
（省略可）サービス アカウントに Secret Manager のロールを付与する
Cloud Build は、Secret の構成中にそのロールがを必要とするサービス アカウントに Secret Manager のシークレット アクセサーのロールを自動的に付与します。このロールが必要なサービス アカウントに自動的に付与されない場合は、次の手順でロールを手動で追加し、サービス アカウントが Secret にアクセスできるようにします。
Google Cloud コンソールで [IAM] ページを開きます。
ロールを付与する Cloud Build サービス アカウントをメモします。
Google Cloud コンソールで [シークレット マネージャー] ページを開きます。
Secret の名前をクリックします。
[Secret の詳細] ページが表示されます。
[権限] タブをクリックします。
[アクセスを許可] をクリックします。
[アクセスを許可] パネルが表示されます。
[プリンシパルを追加] セクションで、Cloud Build サービス アカウントに関連付けられているメールアドレスを追加します。
[ロールの割り当て] セクションで、[Secret Manager] > [Secret Manager シークレット アクセサー] を選択します。
[保存] をクリックします。
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 フィールドを使用して、ステータスが SUCCESS、FAILURE、または 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_time、build.start_time、build.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_NAME と REPO_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}$")`
デフォルトの置換値のリストについては、デフォルトの置換の使用をご覧ください。
次のステップ
- トリガーを作成および管理する方法を学習する。
- Bitbucket Server でホストされるリポジトリをビルドする方法を確認する。
- 手動でビルドを開始する方法を確認する。
- ビルド結果を表示する方法を学習する。
- ビルドエラーをトラブルシューティングする方法について学習する。