Cloud Build は、Slack や SMTP サーバーなどの選択したチャネルに通知を送信することで、ビルド更新を通知します。このページでは、Slack Notifier を使用して通知を構成する方法について説明します。
始める前に
-
Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.
- Google Cloud CLI をインストールする。
Slack 通知を構成する
次のセクションでは、Slack Notifier を使用して Slack 通知を手動で構成する方法を説明します。構成を手動で行わず、自動化する場合は、通知の構成の自動化をご覧ください。
Slack 通知を構成するには:
目的の Slack ワークスペースに Slack アプリを作成します。
Cloud Build から Slack にメッセージを投稿するには、受信 Webhook を有効にします。
Slack アプリに移動して、受信 Webhook の URL を探します。URL は次のようになります。
http://hooks.slack.com/services/...
受信 Webhook URL をシークレット マネージャーに保存します。
Google Cloud コンソールで [シークレット マネージャー] ページを開きます。
[シークレットの作成] をクリックします。
シークレットの名前を入力します。
[シークレットの値] の下に、Slack アプリの受信 Webhook URL を追加します。
シークレットを保存するには、[シークレットの作成] をクリックします。
Cloud Run サービス アカウントにはプロジェクトの編集者ロールが存在する場合がありますが、編集者ロールは Secret Manager のシークレットにアクセスするのには不十分です。Cloud Run サービス アカウントにシークレットへのアクセス権を付与する必要があります。
Google Cloud コンソールで [IAM] ページに移動します。
プロジェクトに関連付けられている Compute Engine のデフォルトのサービス アカウントを見つけます。
Compute Engine のデフォルトのサービス アカウントは次のようになります。
project-number-compute@developer.gserviceaccount.com
Compute Engine のデフォルトのサービス アカウントをメモしておきます。
Google Cloud コンソールで [シークレット マネージャー] ページを開きます。
Slack アプリのシークレットを含むシークレット名をクリックします。
[権限] タブで、[メンバーを追加] をクリックします。
プロジェクトに関連付けられている Compute Engine のデフォルトのサービス アカウントをメンバーとして追加します。
ロールとして Secret Manager のシークレット アクセサー権限を選択します。
[保存] をクリックします。
Cloud Run サービス アカウントに、Cloud Storage バケットの読み取り権限を付与します。
Google Cloud コンソールで [IAM] ページに移動します。
プロジェクトに関連付けられている Compute Engine のデフォルトのサービス アカウントを見つけます。
Compute Engine のデフォルトのサービス アカウントは次のようになります。
project-number-compute@developer.gserviceaccount.com
Compute Engine のデフォルトのサービス アカウントを含む行の鉛筆アイコンをクリックします。[アクセスを編集] タブが表示されます。
[別の役割を追加] をクリックします。
次のロールを追加します。
- ストレージ オブジェクト閲覧者
[保存] をクリックします。
Notifier 構成ファイルを作成し、ビルドイベントに Slack Notifier とフィルタを構成します。
次の Notifier 構成ファイルの例では、
filter
フィールドで Common Expression Language を使用し、変数build
を指定し、SUCCESS
ステータスでビルドイベントをフィルタリングします。apiVersion: cloud-build-notifiers/v1 kind: SlackNotifier metadata: name: example-slack-notifier spec: notification: filter: build.status == Build.Status.SUCCESS params: buildStatus: $(build.status) delivery: webhookUrl: secretRef: webhook-url template: type: golang uri: gs://example-gcs-bucket/slack.json secrets: - name: webhook-url value: projects/project-id/secrets/secret-name/versions/latest
ここで
buildStatus
は、ユーザー定義のパラメータです。このパラメータは、$(build.status) の値、ビルドのステータスです。webhook-url
は、この例で使用されている構成変数です。シークレット マネージャーに格納されている Slack Webhook URL のパスを参照します。ここで指定する変数名は、secrets
のname
フィールドに一致させる必要があります。project-id
は、Google Cloud プロジェクトの ID です。secret-name
は Slack Webhook URL を含むシークレットの名前です。uri
フィールドはslack.json
ファイルを参照します。このファイルは、Cloud Storage でホストされる JSON テンプレートが含まれており、Slack スペースへの通知メッセージを表します。JSON テンプレート ファイルは、Slack の blockkit 機能を活用します。テンプレート ファイルの例を表示するには、cloud-build-notifiers リポジトリの
slack.json
ファイルをご覧ください。
サンプルについては、Slack Notifier の Notifier 構成ファイルをご覧ください。
フィルタに使用できるその他のフィールドについては、ビルドリソースをご覧ください。フィルタリングに関するその他の例については、CEL を使用してビルドイベントをフィルタリングするをご覧ください。
通知機能構成ファイルを Cloud Storage バケットにアップロードします。
Cloud Storage バケットがない場合は、次のコマンドを実行してバケットを作成します。ここで、bucket-name は命名要件に従って、バケットに付ける名前です。
gsutil mb gs://bucket-name/
Notifier 構成ファイルをバケットにアップロードします。
gsutil cp config-file-name gs://bucket-name/config-file-name
ここで
bucket-name
はバケットの名前です。config-file-name
は構成ファイルの名前です。
Notifier を Cloud Run にデプロイします。
gcloud run deploy service-name \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \ --no-allow-unauthenticated \ --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
ここで
service-name
は、イメージをデプロイする Cloud Run サービスの名前です。config-path
は、Slack 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 にあります。プロジェクトに認証トークンを作成する Pub/Sub 権限を付与します。
gcloud projects add-iam-policy-binding project-id \ --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \ --role=roles/iam.serviceAccountTokenCreator
ここで
project-id
は、Google Cloud プロジェクトの ID です。project-number
は Google Cloud プロジェクト番号です。
Pub/Sub サブスクリプション ID を表すサービス アカウントを作成します。
gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"
cloud-run-pubsub-invoker
を使用するか、Google Cloud プロジェクト内で一意の名前を使用します。cloud-run-pubsub-invoker
サービスアカウントに Cloud RunInvoker
権限を付与します。gcloud run services add-iam-policy-binding service-name \ --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \ --role=roles/run.invoker
ここで
service-name
は、イメージをデプロイする Cloud Run サービスの名前です。project-id
は、Google Cloud プロジェクトの ID です。
cloud-builds
トピックを作成して、Notifier のビルド更新メッセージを受信します。gcloud pubsub topics create cloud-builds
Notifier に Pub/Sub push サブスクライバーを作成します。
gcloud pubsub subscriptions create subscriber-id \ --topic=cloud-builds \ --push-endpoint=service-url \ --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
ここで
subscriber-id
は、サブスクリプションに付ける名前です。service-url
は、Cloud Run によって生成された、新しいサービスの URL です。project-id
は、Google Cloud プロジェクトの ID です。
これで Cloud Build プロジェクトの通知が設定されました。次にビルドを呼び出したときに、構成したフィルタとビルドが一致すると、Slack に通知が届きます。
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
は、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")
置換によるフィルタリング
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 ビルド構成ファイルを作成する方法を学習する。