Cloud Build では、着信 Webhook イベントの認証と受け入れができる Webhook トリガーを定義できます。これらのイベントはカスタム URL に送信されると、Bitbucket.com、Bitbucket Server、GitLab などの外部システムと外部ソースコード管理システムを Webhook イベントを介して Cloud Build に直接接続できます。
Webhook トリガーを使用すると、トリガーを作成するときにソースを指定せずにインライン ビルド構成ファイルを定義できます。インライン ビルド構成を使用すると、Git オペレーションを制御し、ビルドの残りの部分を定義できます。
このページでは、Webhook イベントに応答してビルドを自動化する Webhook トリガーを作成する方法について説明します。
始める前に
-
Enable the Cloud Build and Secret Manager APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
このページで
gcloudコマンドを使用するには、Google Cloud CLI をインストールします。
Webhook トリガーを作成する
コンソール
Google Cloud コンソールを使用して Webhook トリガーを作成するには:
[トリガー] ページを開く
ページ上部でプロジェクトを選択し、[開く] をクリックします。
[トリガーを作成] をクリックします。
次のトリガー設定を入力します。
- 名前: トリガーの名前。
リージョン: トリガーのリージョンを選択します。
トリガーに関連付けられたビルド構成ファイルでプライベート プールが指定されている場合、Cloud Build は、そのプライベート プールを使用してビルドを実行します。この場合、トリガーで指定するリージョンは、プライベート プールを作成したリージョンと一致する必要があります。
トリガーに関連付けられたビルド構成ファイルでプライベート プールが指定されていない場合、Cloud Build はデフォルトのプールを使用してトリガーと同じリージョンでビルドを実行します。
- 説明（省略可）: トリガーの説明。
- イベント: [Webhook イベント] を選択して、受信 Webhook イベントにレスポンスしてビルドを開始するトリガーを設定します。
Webhook URL: Webhook URL を使用して、受信 Webhook イベントを認証します。
シークレット: 受信 Webhook イベントを認証するためのシークレットが必要になります。新しいシークレットを作成することも、既存のシークレットを使用することもできます。 このシークレットは、SSH 認証鍵に関連付けられたシークレットとは別のものです。
新しいシークレットを作成するには:
- [新しいシークレット（Cloud Build で生成）を使用する] を選択します。
[シークレットの作成] をクリックします。
[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 "Content-type: 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 トリガーの実行時にビルドするソースを選択します。インライン ビルド構成を指定する場合は、次のソースを指定する必要はありません。 ソースとして [第 1 世代] または [第 2 世代] を指定できます。詳細については、Cloud Build リポジトリをご覧ください。
リポジトリ: 使用可能なリポジトリのリストから、ビルドするリポジトリを選択します。
ブランチまたはタグ: ブランチまたはタグの値にマッチングさせる正規表現を指定します。有効な正規表現の構文については、RE2 構文をご覧ください。
コメント制御: イベントとして pull リクエスト（GitHub アプリのみ）を選択した場合は、ビルドをトリガーによって自動的に実行するかどうか、次のいずれかのオプションを選択します。
Required except for owners and collaborators: pull リクエストがリポジトリ所有者または共同編集者によって作成または更新されると、ビルドが自動的にトリガーによって実行されます。外部の投稿者がアクションを開始する場合、その pull リクエストで所有者または共同編集者が
/gcbrunにコメントした後にのみビルドが実行されます。必須: 投稿者を問わず pull リクエストが作成または更新されると、所有者または共同編集者が pull リクエストに
/gcbrunとコメントした後にのみビルドが実行されます。ビルドは、pull リクエストが変更されるたびに実行されます。不要: 投稿者を問わず pull リクエストが作成または更新されると、ビルドが自動的にトリガーで実行されます。
構成: ビルドに使用するリモート リポジトリにあるビルド構成ファイルを選択するか、インライン ビルド構成ファイルを作成します。ソース リポジトリを指定しない場合は、構成オプションとして [インライン] ビルド構成ファイルを選択する必要があります。
- タイプ: ビルドに使用する構成のタイプを選択します。
- 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 コンソールで [エディタを開く] をクリックして、YAML または JSON 構文でビルド構成ファイルを書き込みます。[完了] をクリックしてビルド構成ファイルを保存します。
次の例では、インライン ビルド構成ファイルのログに「hello world」とエコーされます。
steps: - name: 'ubuntu' args: ['echo', 'hello world']- リポジトリ: 構成ファイルがリモート リポジトリにある場合は、ビルド構成ファイル、
- タイプ: ビルドに使用する構成のタイプを選択します。
置換（省略可）: ビルド構成オプションとしてビルド構成ファイルを選択した場合、またはインライン ビルド構成ファイルを作成した場合、このフィールドを使用して、トリガー固有の置換変数を定義できます。置換変数の値を定義するときに、ペイロード バインディングを使用してデータを取得することもできます。
フィルタ（省略可）: 置換変数に基づいてビルドを実行するかどうかを決定するルールをトリガー内に作成できます。
- [作成] をクリックしてビルドトリガーを作成します。
gcloud
Webhook トリガーを作成するには、以下を実行します。
gcloud builds triggers create webhook \ --name=TRIGGER_NAME \ --repo=PATH_TO_REPO \ --repo-type=REPO_TYPE \ --secret=PATH_TO_SECRET \ --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \ --subscription-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+REPO_TYPEは、ビルドを呼び出すリポジトリのタイプです。PATH_TO_SECRETは、Secret Manager に保存されているシークレットへのパスです。例:projects/my-project/secrets/my-secret/versions/2PATH_TO_INLINE_BUILD_CONFIGは、--inline-configを使用する場合のインライン ビルド構成ファイルへのパスです。TAG_NAMEは、タグでビルドのトリガーを設定するタグの名前です。--build-configを使用する場合は、PATH_TO_BUILD_CONFIGがビルド構成ファイルへのパスです。BRANCH_NAMEは、ブランチでビルドのトリガーを設定する場合、ブランチの名前です。
（省略可）API キーを取得する
受信 Webhook イベントを認証するには、API キーが必要です。
API キーを取得するには:
Google Cloud コンソールで [認証情報] ページを開きます。
[認証情報を作成] をクリックします。
[API キー] をクリックします。
作成した API キーとともにダイアログが表示されます。API キーをメモします。
プロダクト アプリケーションのキーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。
キーを制限する方法については、API キーの制限を適用するをご覧ください。
（省略可）サービス アカウントに Secret Manager のロールを付与する
Cloud Build は、Secret の構成中にそのロールがを必要とするサービス アカウントに Secret Manager のシークレット アクセサーのロールを自動的に付与します。このロールが必要なサービス アカウントに自動的に付与されない場合は、次の手順でロールを手動で追加し、サービス アカウントが Secret にアクセスできるようにします。
Google Cloud コンソールで [IAM] ページを開きます。
省略可: Google 提供のアカウントを表示するには、[Google 提供のロール付与を含める] チェックボックスをオンにします。
ロールを付与するビルド サービス アカウントをメモします。
Google Cloud コンソールで [Secret Manager] ページを開きます。
シークレットの名前をクリックします。
[Secret の詳細] ページが表示されます。
[権限] タブをクリックします。
[アクセス権を付与] をクリックします。
[アクセスを許可] パネルが表示されます。
[プリンシパルを追加] セクションで、ビルド サービス アカウントに関連付けられているメールアドレスを追加します。
[ロールの割り当て] セクションで、[Secret Manager] > [Secret Manager シークレット アクセサー] を選択します。
[保存] をクリックします。
次のステップ
- トリガーを作成および管理する方法を学習する。
- Bitbucket Server でホストされるリポジトリをビルドする方法を確認する。
- 手動でビルドを開始する方法を確認する。
- ビルド結果を表示する方法を学習する。
- ビルドエラーをトラブルシューティングする方法について学習する。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2026-02-02 UTC。