Configure Google Chat notifications

Cloud Build can notify you of build updates by sending you notifications to selected channels, such as Slack or your SMTP server. This page explains how to configure notifications using the Google Chat notifier.

Before you begin

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, 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 the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

Install the Google Cloud CLI.

Configuring Google Chat notifications

The following section explains how you can manually configure Google Chat notifications using the Google Chat notifier. If you would like to automate the configuration instead, see Automating configuration for notifications.

To configure Google Chat notifications:

Create a space in Google Chat.
Within the created space, create an incoming webhook to post messages from Cloud Build to Google Chat. Your URL will look similar to the following:
```
https://chat.googleapis.com/v1/spaces/... 
```
Store your incoming webhook URL in Secret Manager:
1. Open the Secret Manager page in the Google Cloud console:
  
  Open the Secret Manager page
2. Click Create secret.
3. Enter a name for your secret.
4. Under Secret value, add your incoming webhook URL for your Google Chat space.
5. To save your secret, click Create secret.
While your Cloud Run service account may have the Editor role for your project, the Editor role isn't sufficient to access your secret in Secret Manager. To give your Cloud Run service account access to your secret, do the following:
1. Go to the IAM page in the Google Cloud console:
  
  Open the IAM page
2. Locate the Compute Engine default service account associated with with your project:
  
  Your Compute Engine default service account will look similar to the following:
```
project-number-compute@developer.gserviceaccount.com 
```
  Take note of your Compute Engine default service account.
  
  Note: By default, Cloud Run runs your notifier images with the Compute Engine default service account and uses it to fetch your secret. To learn more about Runtime service accounts, see Runtime service account.
3. Open the Secret Manager page in the Google Cloud console:
  
  Open the Secret Manager page
4. Click the secret name that contains the secret for your Google Chat webhook.
5. In the Permissions tab, click Add member.
6. Add the Compute Engine default service account associated with your project as a member.
7. Select Secret Manager Secret Accessor permission as the role.
8. Click Save.
Give your Cloud Run service account permission to read from Cloud Storage buckets:
1. Go to the IAM page in the Google Cloud console:
  
  Open the IAM page
2. Locate the Compute Engine default service account associated with with your project:
  
  Your Compute Engine default service account will look similar to the following:
```
project-number-compute@developer.gserviceaccount.com 
```
3. Click the pencil icon in the row containing your Compute Engine default service account. You will see the Edit access tab.
4. Click Add another role.
5. Add the following role:
  - Storage Object Viewer
  Note: If you want to grant permissions at the bucket level instead of the project level, add the Storage Legacy Object Owner role to your bucket when you create one. To learn more, see Granting roles at the project level, bucket level, or managed folder level.
6. Click Save.
Write a notifier configuration file to configure your Google Chat notifier and filter on build events:

In the following example notifier configuration file, the filter field uses Common Expression Language with the available variable, build, to filter build events with a SUCCESS status:
```
apiVersion: cloud-build-notifiers/v1 kind: GoogleChatNotifier metadata:  name: example-googlechat-notifier spec:  notification:  filter: build.status == Build.Status.SUCCESS  delivery:  webhookUrl:  secretRef: webhook-url  secrets:  - name: webhook-url  value: projects/project-id/secrets/secret-name/versions/latest 
```
Where:
- webhook-url is the configuration variable used in this example to reference the Google Chat webhook URL path stored in Secret Manager. The variable name you specify here should match the name field under secrets.
- project-id is the ID of your Google Cloud project.
- secret-name is the name of your secret that contains your Google Chat webhook URL.
To view the example, see the notifier configuration file for the Google Chat notifier.

For additional fields you can filter by, see the Build resource. For additional filtering examples, see Using CEL to filter build events.
Upload your notifier configuration file to a Cloud Storage bucket:
1. If you don't have a Cloud Storage bucket, run the following command to create a bucket, where bucket-name is the name you want to give your bucket, subject to naming requirements.
```
gcloud storage buckets create gs://bucket-name/ 
```
2. Upload the notifier configuration file to your bucket:
```
gcloud storage cp config-file-name gs://bucket-name/config-file-name 
```
  Where:
  - bucket-name is the name of your bucket.
  - config-file-name is the name of your configuration file.
Deploy your notifier to Cloud Run:
```
 gcloud run deploy service-name \  --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/googlechat:latest \  --no-allow-unauthenticated \  --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id 
```
Where:
- service-name is the name of the Cloud Run service to which you're deploying the image.
- config-path is the path to the notifier config file for your Google Chat notifier, gs://bucket-name/config-file-name.
- project-id is the ID of your Google Cloud project.
The gcloud run deploy command pulls the latest version of the hosted image from the Cloud Build-owned Artifact Registry. Cloud Build supports notifier images for nine months. After nine months, Cloud Build deletes the image version. If you would like to use a prior image version, you will need to specify the full semantic version of the image tag in the image attribute of your gcloud run deploy command. Previous image versions and tags can be found in Artifact Registry.

Note: While running this command, you may be prompted to specify additional arguments such as --region or --platform. To learn more about parameters you can pass to the gcloud run deploy command, see Deploying to Cloud Run. If you are unable to deploy your notifier using this command, see the Cloud Run troubleshooting guide for solutions on how to resolve Deployment errors.
Grant Pub/Sub permissions to create authentication tokens in your Google Cloud project:
```
 gcloud projects add-iam-policy-binding project-id \  --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \  --role=roles/iam.serviceAccountTokenCreator 
```
Where:
- project-id is the ID of your Google Cloud project.
- project-number is your Google Cloud project number.
Note: If the Pub/Sub service account doesn't exist on your project, see Create and use subscriptions.
Create a service account to represent your Pub/Sub subscription identity:
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker" 
```
You can use cloud-run-pubsub-invoker or use a name unique within your Google Cloud project.
Give the cloud-run-pubsub-invoker service account the Cloud Run Invoker permission:
```
gcloud run services add-iam-policy-binding service-name \  --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \  --role=roles/run.invoker 
```
Where:
- service-name is the name of the Cloud Run service to which you're deploying the image.
- project-id is the ID of your Google Cloud project.
Create the cloud-builds topic to receive build update messages for your notifier:
```
gcloud pubsub topics create cloud-builds 
```
You can also define a custom topic name in your build config file so that messages are sent to the custom topic instead. In this case, you would create a topic with the same custom topic name:
```
gcloud pubsub topics create topic-name 
```
For more information, see Pub/Sub topics for build notifications.
Create a Pub/Sub push subscriber for your notifier:
```
 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 
```
Where:
- subscriber-id is the name you want to give your subscription.
- service-url is the Cloud Run-generated URL for your new service.
- project-id is the ID of your Google Cloud project.

Notifications for your Cloud Build project are now set up. The next time you invoke a build, you will receive a notification in Google Chat if the build matches the filter you've configured.

Using CEL to filter build events

Cloud Build uses CEL with the variable, build, on fields listed in the Build resource to access fields associated with your build event such as your trigger ID, image list, or substitution values. You can use the filter string to filter build events in your build config file using any field listed in the Build resource. To find the exact syntax associated with your field, see the cloudbuild.proto file.

Filtering by trigger ID

To filter by trigger ID, specify the value of your trigger ID in the filter field using build.build_trigger_id, where trigger-id is your trigger ID as a string:

filter: build.build_trigger_id == trigger-id

Filtering by status

To filter by status, specify the build status you want to filter on in the filter field using build.status.

The following example shows how to filter build events with a SUCCESS status using the filter field:

filter: build.status == Build.Status.SUCCESS

You can also filter builds with varying statuses. The following example shows how to filter build events that have a SUCCESS, FAILURE, or TIMEOUT status using the filter field:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

To see additional status values you can filter by, see Status under the Build resource reference.

Filtering by tag

To filter by tag, specify the value of your tag in the filter field using build.tags, where tag-name is the name of your tag:

filter: tag-name in build.tags

You can filter based on the number of tags specified in your build event using size. In the following example, the filter field filters build events that have exactly two tags specified with one tag specified as v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Filtering by images

To filter by images, specify the value of your image in the filter field using build.images, where image-name is the full name of your image as listed in Artifact Registry such as us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

In the following example, the filter filters on build events that have either us-east1-docker.pkg.dev/my-project/docker-repo/image-one or us-east1-docker.pkg.dev/my-project/docker-repo/image-two specified as image names:

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

Filtering by time

You can filter build events based on a build's create time, start time, or finish time by specifying one of the following options in your filter field: build.create_time, build.start_time, or build.finish_time.

In the following example, the filter field uses timestamp to filter build events with a request time to create the build at July 20, 2020 at 6:00 AM:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

You can also filter on build events by time comparisons. In the following example, the filter field uses timestamp to filter build events with a start time between July 20, 2020 at 6:00 AM and July 30, 2020 at 6:00 AM.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

To learn more about how timezones are expressed in CEL, see the language definition for timezones.

To filter by duration of a build, you can use duration to compare timestamps. In the following example, the filter field uses duration to filter build events with a builds that run for at least five minutes:

filter: build.finish_time - build.start_time >= duration("5m")

Filtering by substitution

You can filter by substitution by specifying the substitution variable in the filter field using build.substitutions. In the following example, the filter field lists builds that contain the substitution variable substitution-variable and checks if the substitution-variable matches the specified substitution-value:

filter: build.substitutions[substitution-variable] == substitution-value

Where:

substitution-variable is the name of your substitution variable.
substitution-value is the name of your substitution value.

You can also filter by default substitution variable values. In the following example, the filter field lists builds that have the branch name master and builds that have the repository name github.com/user/my-example-repo. The default substitution variables BRANCH_NAME and REPO_NAME are passed in as keys to the build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

If you want to filter on strings using regular expressions, you can use the built-in matches function. In the example below, the filter field filters for builds with a status of FAILURE or TIMEOUT and that also have a build substitution variable TAG_NAME with a value that matches the regular expression v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")

To see a list of default substitution values, see Using default substitutions.

What's next

Learn about Cloud Build notifiers.
Learn how to subscribe to build notifications.
Learn how to write a Cloud Build build configuration file.