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

第 1 世代 第 2 世代

Cloud Build では、着信 Webhook イベントの認証と受け入れができる Webhook トリガー を定義できます。これらのイベントはカスタム URL に送信されると、Bitbucket.com、Bitbucket Server、GitLab などの外部システムと外部ソースコード管理システムを Webhook イベントを介して 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 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

  API を有効にする

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

  注: すでに gcloud CLI をインストールしている場合は、 最新のバージョンがインストールされていることを確認してください。gcloud components update

• Webhook トリガーがソースとして Cloud Build リポジトリを使用する場合は、 Cloud Build リポジトリを よく理解していることを確認してください。

Webhook トリガーを作成する

コンソール

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

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

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

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

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

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

   • 名前: トリガーの名前。

   • リージョン: トリガーのリージョンを選択します。

     • トリガーに関連付けられたビルド構成ファイルで プライベート プールが指定されている場合、 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 のロールを付与するをご覧ください。

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

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

        これらの手順を完了すると、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']
     

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

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

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

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 はトリガーの region です。この値は「global」以外のリージョンにする必要があります。
• SECRET_NAME は Secret Manager に保存されているシークレットの名前です。
• 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（省略可）は、トリガーの CEL フィルタ式です（'_SUB_ONE == "prod"' など）。
• （省略可）コマンドに --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 トリガーの作成時に Secret を構成すると、ほとんどの場合、Cloud Build は、そのロールを必要とするサービス アカウントに Secret Manager のシークレット アクセサー のロールを自動的に付与します。ただし、既存のシークレットを使用する場合は、Secret Manager のシークレット アクセサーのロールを Cloud Build サービス アカウントに手動で付与する必要もあります。

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

   [IAM] ページを開く

2. 省略可: Google 提供のアカウントを表示するには、[Google 提供のロール付与を含みます] チェックボックスをオンにします。

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

4. コンソールで [Secret Manager] ページを開きます。 Google Cloud

   [Secret Manager] ページを開く

5. シークレットの名前をクリックします。

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

   1. [権限] タブをクリックします。

   2. [アクセス権を付与] をクリックします。

      [アクセス権の付与] パネルが表示されます。

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

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

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

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

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

API キーを取得するには:

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

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

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

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

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

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

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

次のステップ

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