HTTP 通知の構成

Cloud Build は、Slack や SMTP サーバーなどの選択したチャネルに通知を送信することで、ビルド更新を通知します。このページでは、HTTP Notifier を使用して通知を構成する方法について説明します。

始める前に

• Cloud Build、Cloud Run、Pub/Sub API を有効にします。

  API を有効にするために必要なロール

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

  API を有効にする

• Google Cloud CLI をインストールします。

HTTP 通知を構成する

次のセクションでは、HTTP Notifier を使用して HTTP 通知を手動で構成し、特定の受信者 URL に POST リクエストを送信する方法について説明します。構成を手動で行わず、自動化する場合は、通知の構成の自動化をご覧ください。

HTTP 通知を構成するには:

HTTP Notifier を使用して、特定の受信者 URL に POST リクエストを送信するには:

1. Cloud Run サービス アカウントに、Cloud Storage バケットの読み取り権限を付与します。

   1. コンソール Google Cloud で、[IAM] ページに移動します。

      [IAM] ページを開く

   2. プロジェクトに関連付けられている Compute Engine のデフォルトのサービス アカウントを見つけます。

      Compute Engine のデフォルトのサービス アカウントは次のようになります。

      PROJECT_NUMBER-compute@
      

   3. Compute Engine のデフォルトのサービス アカウントを含む行の鉛筆アイコンをクリックします。[アクセスを編集] タブが表示されます。

   4. [別のロールを追加] をクリックします。

   5. 次のロールを追加します。

      • ストレージ オブジェクト閲覧者
      注: プロジェクト レベルではなくバケットレベルで権限を付与する場合は、バケットを作成する際に Storage レガシー オブジェクト オーナーのロールをそのバケットに追加します。詳しくは、プロジェクト レベルのロールとバケットレベルのロールをご覧ください。

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

2. Notifier 構成ファイルを作成し、ビルドイベントに HTTP Notifier とフィルタを構成します。

   次の Notifier 構成ファイルの例では、filter フィールドで Common Expression Language を使用し、変数 build を指定し、SUCCESS ステータスでビルドイベントをフィルタリングします。

   apiVersion: cloud-build-notifiers/v1
   kind: HTTPNotifier
   metadata:
     name: example-http-notifier
   spec:
     notification:
       filter: build.status == Build.Status.SUCCESS
       params:
         buildStatus: $(build.status)
       delivery:
         # The `http(s)://` protocol prefix is required.
         url: URL
       template:
         type: golang
         uri: gs://BUCKET_NAME/http.json
   

   ここで

   • buildStatus は、ユーザー定義のパラメータです。このパラメータは、$(build.status) の値、ビルドのステータスです。
   • url は、この例でリクエストの URL を指定するために使用される構成変数です。
   • BUCKET_NAME はバケットの名前です。
   • URL は、受信者サーバーとして指定する URL です。

   • uri フィールドは http.json ファイルを参照します。このファイルは Cloud Storage でホストされる JSON テンプレートを参照し、webhook エンドポイントへの JSON ペイロードを表します。

     試験運用版 — テンプレートを使用して通知をカスタマイズする

     この機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります 。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、 リリース ステージの説明をご覧ください。

     テンプレート ファイルの例を表示するには、http.json ファイルを cloud-build-notifiers リポジトリでご覧ください。

   サンプルについては、HTTP Notifier の Notifier 構成ファイルをご覧ください。

   フィルタに使用できるその他のフィールドについては、ビルドリソースをご覧ください。フィルタリングに関するその他の例については、CEL を使用したビルドイベントのフィルタリングをご覧ください。

3. 通知機能構成ファイルを Cloud Storage バケットにアップロードします。

   1. Cloud Storage バケットがない場合は、次のコマンドを実行して バケットを作成します。ここで、BUCKET_NAME は命名要件に従って、バケットに付ける名前です。

      gcloud storage buckets create gs://BUCKET_NAME/
      

   2. Notifier 構成ファイルをバケットにアップロードします。

      gcloud storage cp CONFIG_FILE_NAME gs://BUCKET_NAME/CONFIG_FILE_NAME
      

      ここで

      • BUCKET_NAME はバケットの名前です。
      • CONFIG_FILE_NAME は、Notifier の構成ファイルの名前です。

4. Notifier を Cloud Run にデプロイします。

    gcloud run deploy SERVICE_NAME \
      --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/http:latest \
      --no-allow-unauthenticated \
      --update-env-vars=CONFIG_PATH=CONFIG_PATH,PROJECT_ID=PROJECT_ID
   

   ここで

   • SERVICE_NAME は、イメージをデプロイする Cloud Run サービスの名前です。
   • CONFIG_PATH は、HTTP Notifier の Notifier 構成ファイルのパスで、gs://BUCKET_NAME/CONFIG_FILE_NAME です。
   • PROJECT_ID は、実際の Google Cloud プロジェクトの ID です。

   gcloud run deploy コマンドは、ホストされたイメージの最新バージョンを Cloud Build が所有する Artifact Registry から pull します。Cloud Build は 9 か月間、Notifier イメージをサポートします。9 か月を過ぎると、イメージのバージョンは削除されます。以前のイメージ バージョンを使用する場合は、gcloud run deploy コマンドの image 属性でイメージタグの完全なセマンティック バージョンを指定する必要があります。以前のイメージ バージョンとタグは、Artifact Registry にあります。

   注: このコマンドの実行中に、--region や --platform などの追加の引数を指定するよう求められる場合があります。gcloud run deploy コマンドに渡すことができるパラメータの詳細については、Cloud Run へのデプロイをご覧ください。このコマンドを使用して Notifier をデプロイできない場合は、 Cloud Run のトラブルシューティング ガイドでデプロイエラーを解決する方法を確認してください。

5. Pub/Sub サブスクリプション ID を表すサービス アカウントを作成します。

   gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
     --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"
   

   ここで

   • SUB_IDENTITY_SERVICE_ACCOUNT はサービス アカウントの名前です。

   • SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME はサービス アカウントの表示名です。

   注: このサービス アカウントは、Pub/Sub サブスクリプションを初めて作成 するときに Google Cloud 作成される Pub/Sub サービス アカウントとは異なります。Pub/Sub サービス アカウントのアドレスは service-PROJECT_NUMBER@gcp-sa-pubsub..
   です。

6. プロジェクトで認証トークンを作成するために必要な権限を Pub/Sub サブスクリプション ID サービス アカウントに 付与します。 Google Cloud

   gcloud iam service-accounts add-iam-policy-binding \
       SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.i \
       --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \
       --role=roles/iam.serviceAccountTokenCreator
   

   ここで

   • PROJECT_ID は、実際の Google Cloud プロジェクトの ID です。

   • PROJECT_NUMBER は Google Cloud プロジェクト番号です。

7. SUB_IDENTITY_SERVICE_ACCOUNT サービス アカウントに Cloud Run Invoker ロールを付与します。

   gcloud run services add-iam-policy-binding SERVICE_NAME \
      --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID. \
      --role=roles/run.invoker
   

   ここで

   • SERVICE_NAME は、イメージをデプロイする Cloud Run サービスの名前です。

   • PROJECT_ID は、実際の Google Cloud プロジェクトの ID です。

8. cloud-builds トピックを作成して、Notifier のビルド更新メッセージを受信します。

   gcloud pubsub topics create cloud-builds
   

   ビルド構成ファイルでカスタム トピック名を定義して 、メッセージがカスタム トピックに送信されるようにすることもできます。この場合は、同じカスタム トピック名でトピックを作成します。

   gcloud pubsub topics create topic-name
   

   詳細については、 ビルド通知の Pub/Sub トピックをご覧ください。

9. Notifier に Pub/Sub push サブスクライバーを作成します。

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=SERVICE_URL \
       --push-auth-service-account=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.

ここで: + SUBSCRIBER_ID は、サブスクリプションに付ける名前です。 + SERVICE_URL は、Cloud Run によって生成された、新しいサービスの URL です。 + PROJECT_ID は、実際の Google Cloud プロジェクトの ID です。

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

これで Cloud Build プロジェクトの通知が設定されました。次に ビルドを呼び出したときに、構成したフィルタとビルドが一致すると、指定された URL にある受信用の HTTP サーバーが ビルド リソースと一致する JSON ペイロードを受信します。

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

注: トリガー ID はトリガーの名前ではありません。トリガー ID を取得するには、次のコマンドを実行します。gcloud beta builds triggers describe trigger-nameここで、trigger-name はトリガーの名前です。このコマンドを実行すると、トリガー 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 は、us-east1-docker.pkg.dev/my-project/docker-repo/image-one などの Artifact Registry に表示されるイメージの完全な名前です。

filter: image-name in build.images

下の例では、filter がイメージ名として us-east1-docker.pkg.dev/my-project/docker-repo/image-one または us-east1-docker.pkg.dev/my-project/docker-repo/image-two が指定されているビルドイベントをフィルタリングします。

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" 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")

注: タイムスタンプは RFC 3339 UTC Zulu 形式で、ナノ秒刻みで、小数点以下 9 桁まで表示できます。

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

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}$")

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

次のステップ

• Cloud Build Notifier の詳細を確認します。
• ビルド通知をサブスクライブする方法を学習する。
• Cloud Build ビルド構成ファイルを作成する方法を学習する。