Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Webhook イベントに応答してビルドを自動化する

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

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

このページでは、Webhook イベントに応答してビルドを自動化する Webhook トリガーを作成する方法について説明します。

注: リポジトリイベントでビルドを自動化するトリガーを作成する場合は、Cloud Build リポジトリトリガーを使用することをおすすめします。Cloud Build リポジトリ（第 2 世代）を使用するリポジトリトリガーは、プログラムで構成でき、GitHub や GitLab のサポートを含むソースプロバイダと統合されています。Cloud Build リポジトリ（第 2 世代）は、Secret Manager を使用して認証トークンと情報を管理します。リポジトリトリガーを使用すると、受信イベントをフィルタし、ビルドステータスをソースプロバイダに返すことができます。また、プライベートネットワークで動作するように構成することもできます。詳細については、リポジトリの概要をご覧ください。

始める前に

Cloud Build API と Secret Manager API が有効になっていない場合は有効にします。
API を有効にするために必要なロール
API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。
API を有効にする

このページで gcloud コマンドを使用するには、Google Cloud CLI をインストールします。
注: すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して、最新のバージョンがインストールされていることを確認してください。
Webhook トリガーで Cloud Build リポジトリをソースとして使用する場合は、Cloud Build リポジトリについて理解しておいてください。

Webhook トリガーを作成する

コンソール

Google Cloud コンソールを使用して Webhook トリガーを作成するには:

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

[ビルドトリガー] ページを開く
ページ上部でプロジェクトを選択し、[開く] をクリックします。
[トリガーを作成] をクリックします。
次のトリガー設定を入力します。
- 名前: トリガーの名前。
- リージョン: トリガーのリージョンを選択します。
  - トリガーに関連付けられたビルド構成ファイルでプライベートプールが指定されている場合、Cloud Build は、そのプライベートプールを使用してビルドを実行します。この場合、トリガーで指定するリージョンは、プライベートプールを作成したリージョンと一致する必要があります。
  - トリガーに関連付けられたビルド構成ファイルでプライベートプールが指定されていない場合、Cloud Build はデフォルトのプールを使用してトリガーと同じリージョンでビルドを実行します。
- 説明（省略可）: トリガーの説明。
- イベント: [Webhook イベント] を選択して、受信 Webhook イベントにレスポンスしてビルドを開始するトリガーを設定します。
- Webhook URL: Webhook URL を使用して、受信 Webhook イベントを認証します。受信 Webhook イベントを認証するためのシークレットが必要になります。新しいシークレットを作成することも、既存のシークレットを使用することもできます。このシークレットは、SSH 認証鍵に関連付けられたシークレットとは別のものです。
  
  シークレットを作成するには:
  1. [新しいシークレット（Cloud Build で生成）を使用する] を選択します。
  2. [シークレットの作成] をクリックします。
    
    [Webhook シークレットを作成] ダイアログが表示されます。
  3. [シークレット名] フィールドにシークレットの名前を入力します。
  4. [シークレットを作成] をクリックしてシークレットを保存します。クリックすると、シークレットが自動的に作成され Secret Manager に保存されます。
  既存の Secret を使用するには:
  1. [既存のシークレットを使用するか独自のシークレットを作成する] を選択します。
  2. [シークレット] フィールドで、使用するシークレットの名前をプルダウンメニューから選択するか、指示に従ってリソース ID でシークレットを追加します。
  3. [シークレットのバージョン] フィールドで、プルダウンメニューからシークレットのバージョンを選択します。
    
    既存のシークレットを使用する場合は、Secret Manager のシークレットアクセサーのロールを Cloud Build サービスアカウント service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com に手動で付与する必要があります。詳しくは、サービスアカウントに Secret Manager のロールを付与するをご覧ください。
    
    Secret を作成または選択すると、Webhook URL のプレビューが表示されます。URL には、Cloud Build によって生成された API キーとシークレットが含まれます。Cloud Build で API キーを取得できない場合は、手動で API キーを URL に追加するか、API キーの取得方法（API キーがない場合）をご覧ください。
    
    この URL を使用して POST メソッドで HTTP リクエストを行うことで、Webhook イベントを呼び出すことができます。
    
    これらの手順を完了すると、Secret Manager のシークレットアクセサーのロールが Cloud Build サービスエージェント service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com に自動的に付与されます。このロールがサービスエージェントに自動的に追加されない場合は、サービスアカウントに Secret Manager のロールを付与するで説明されている手順を実行してください。
- ソース（省略可）: インラインビルド構成を指定する場合は、ソースを指定する必要はありません。それ以外の場合は、次の操作を行います。
  - リポジトリの生成: [第 2 世代]を選択します。
  - リポジトリ: 使用可能なリポジトリのリストから、ビルドするリポジトリを選択します。リポジトリのリージョンは、トリガーのリージョンと一致する必要があります。
  - ブランチまたはタグ: ブランチまたはタグの値にマッチングさせる正規表現を指定します。有効な正規表現の構文については、RE2 構文をご覧ください。
  - コメント制御: イベントとして pull リクエストを選択した場合は、トリガーがビルドを自動的に呼び出すかどうかを制御する次のいずれかのオプションを選択します。
    
    警告: リポジトリへの読み取りアクセス権を持つすべてのユーザーが pull リクエストを送信できます。これにより、pull リクエスト内のソースコードの変更を含むビルドが実行される可能性が生じます。この動作を無効にするには、公開リポジトリで pull リクエストを行うときに、手動承認を使用してビルドを制御することをおすすめします。トリガーのビルド時間に関する権限の詳細もご覧ください。
    - 必須（オーナーと共同編集者を除く）: 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 構文を使用してビルド構成ファイルを書き込みます。[完了] をクリックしてビルド構成ファイルを保存します。
      
      注: Dockerfile または Buildpacks では、インラインビルド構成はサポートされていません。
  次の例では、インラインビルド構成ファイルのログに「hello world」とエコーされます。
```
 steps:
 - name: 'ubuntu'
   args: ['echo', 'hello world']
```
- 置換（省略可）: ビルド構成オプションとしてビルド構成ファイルを選択した場合、またはインラインビルド構成ファイルを作成した場合、このフィールドを使用して、トリガー固有の置換変数を定義できます。置換変数の値を定義するときに、ペイロードバインディングを使用してデータを取得することもできます。
- フィルタ（省略可）: 置換変数に基づいてビルドを実行するかどうかを決定するルールをトリガー内に作成できます。
[作成] をクリックしてビルドトリガーを作成します。

gcloud

Webhook トリガーを作成するには、以下を実行します。

gcloud builds triggers create webhook \
  --trigger-config=TRIGGER_CONFIG_PATH \
  --name=TRIGGER_NAME \
  --description=DESCRIPTION \
  --region=REGION \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --service-account=SERVICE_ACCOUNT \ 
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \ 
  --build-config=PATH_TO_BUILD_CONFIG \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --dockerfile=DOCKERFILE \
  --dockerfile-dir=DOCKERFILE_DIR \
  --dockerfile-image=DOCKERFILE_IMAGE \
  --tag=TAG_NAME \
  --branch=BRANCH_NAME \
  --substitutions=_SUB_ONE=SUBSTITUTION \
  --subscription-filter=FILTER \
  --require-approval

ここで

TRIGGER_CONFIG_PATH は、トリガー構成ファイルへのパスです。トリガー構成ファイルを使用する場合、name、description、region、secret、service-account、subscription-filter、substitution の各フィールドは未定義のままにする必要があります。詳細については、Cloud Build のリファレンスドキュメントの BuildTrigger をご覧ください。
TRIGGER_NAME はトリガーの名前です。
DESCRIPTION（省略可）は、トリガーの説明です。
REGION はトリガーのリージョンです。この値は「global」以外のリージョンにする必要があります。
SECRET_NAME はシークレットマネージャーに保存されているシークレットの名前です。
SECRET_VERSION は、Secret Manager に保存されているシークレットに関連付けられたバージョンです。
SERVICE_ACCOUNT は、ビルドトリガーに関連するユーザー制御のオペレーションをすべて実行するために使用されるサービスアカウントです。サービスアカウントを定義しない場合、Cloud Build はデフォルトの Cloud Build サービスアカウントを使用します。
PROJECT_ID は Google Cloud プロジェクト ID です。
CONNECTION_NAME はホスト接続の名前です。
REPO_NAME はリポジトリの名前です。
PATH_TO_BUILD_CONFIG は、ビルド構成ファイルへのパスです。トリガーが Cloud Build リポジトリ内のビルド構成ファイルを参照する場合は、このパラメータを使用します。このパラメータを設定した場合、inline-config を定義したり、Dockerfile のパラメータを使用したりすることはできません。
PATH_TO_INLINE_BUILD_CONFIG は、インラインビルド構成へのパスです。トリガーがローカルビルド構成ファイルを参照する場合は、このパラメータを使用します。このパラメータを設定すると、build-config を定義したり、Dockerfile のパラメータを使用したりすることはできません。
DOCKERFILE は、Dockerfile へのパスです。トリガーが Dockerfile を参照する場合は、このパラメータを使用します。Dockerfile パラメータを設定した場合、build-config または inline-config を定義することはできません。
DOCKERFILE_DIR は Dockerfile のディレクトリです。
DOCKERFILE_IMAGE は、Cloud Build がビルドする Docker イメージの名前です。
BRANCH_NAME は、ブランチでビルドのトリガーを設定する場合、ブランチの名前です。このパラメータを設定した場合、tag は定義できません。
TAG_NAME は、タグでビルドのトリガーを設定するタグの名前です。このパラメータを設定した場合、branch は定義できません。
SUBSTITUTION（省略可）は、ビルド仕様で置き換えるパラメータです。例: _SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)'
FILTER（省略可）は、'_SUB_ONE == "prod"' などのトリガーの CEL フィルタ式です。
（省略可）コマンドに --require-approval が存在する場合、Cloud Build はトリガーされたビルドの手動承認を必要とします。

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 のロールを付与する

Webhook トリガーの作成時にシークレットを構成すると、ほとんどの場合、Cloud Build は、ロールを必要とするサービスアカウントに Secret Manager のシークレットアクセサーのロールを自動的に付与します。ただし、既存のシークレットを使用する場合は、Cloud Build サービスアカウントに Secret Manager のシークレットアクセサーのロールを手動で付与する必要がある場合もあります。

Google Cloud コンソールで [IAM] ページを開きます。

[IAM] ページを開く
省略可: Google 提供のアカウントを表示するには、[Google 提供のロール付与を含める] チェックボックスをオンにします。
ロールを付与するビルドサービスアカウントをメモします。
Google Cloud コンソールで [Secret Manager] ページを開きます。

[シークレットマネージャー] ページを開く
シークレットの名前をクリックします。

[Secret の詳細] ページが表示されます。
1. [権限] タブをクリックします。
2. [アクセス権を付与] をクリックします。
  
  [アクセスを許可] パネルが表示されます。
3. [プリンシパルを追加] セクションで、ビルドサービスアカウントに関連付けられているメールアドレスを追加します。
4. [ロールの割り当て] セクションで、[Secret Manager] > [Secret Manager シークレットアクセサー] を選択します。
5. [保存] をクリックします。

（省略可）API キーを取得する

受信 Webhook イベントを認証するには、API キーが必要です。この API キーは、Webhook トリガーを構成するときに選択するシークレットの一部です。API キーをまだ取得していない場合、または Google Cloud コンソールでシークレットを構成するときに Cloud Build で API キーを取得できなかった場合は、API キーを手動で作成できます。

API キーを取得するには:

Google Cloud コンソールで [認証情報] ページを開きます。

[認証情報] ページを開く
[認証情報を作成] をクリックします。
[API キー] をクリックします。

作成した API キーとともにダイアログが表示されます。API キーをメモします。
プロダクトアプリケーションのキーを制限する場合は、[キーを制限] をクリックして、キーを保護する追加の手順を行います。制限しない場合は、[閉じる] をクリックします。

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

次のステップ

トリガーを作成および管理する方法を学習する。
Bitbucket Server でホストされるリポジトリをビルドする方法を確認する。
手動でビルドを開始する方法を確認する。
ビルド結果を表示する方法を学習する。
ビルドエラーをトラブルシューティングする方法について学習する。