Cloud Build can notify you of build updates by sending you notifications to desired channels, such as Slack or your SMTP server. This page explains how to configure notifications using the SMTP notifier.
Before you begin
- Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.
- Install the
gcloud
command-line tool.
Cloud Build notifiers
Cloud Build sends all build event updates,
along with build metadata, to Pub/Sub on the cloud-builds
topic.
Cloud Build notifiers can be configured to listen to that
topic, filter the messages it receives, and send messages to your service.
Cloud Build notifiers are Docker images that can be run as containers on Cloud Run. When polled by a subscriber application, Cloud Build notifiers use push subscriptions to deliver messages to the configured service. All notifiers use a common YAML spec for configuration, stored in Cloud Storage.
Cloud Build provides and maintains deployable notifier images in
the cloud-build-notifiers
repository. The following table lists available
notifiers:
Notifier | Description |
---|---|
bigquery |
writes build data to a BigQuery table |
http |
sends a JSON payload to another HTTP endpoint |
slack |
uses a Slack webhook to post messages to a Slack channel |
smtp |
sends emails via an SMTP server |
bigquery |
pushes build data to a BigQuery instance |
Configuring email notifications
To send email notifications, you will need a running SMTP server and access to an account on that server, including the account's username and password that will be used to send notifications. Please ensure that your SMTP server's delivery quotas can handle the volume of email you expect to generate.
The following section explains how you can manually configure email notifications using the SMTP notifier. If you would like to automate the configuration instead, see Automating configuration for notifications.
To configure email notifications:
Store the sender's email account password in Secret Manager:
Open the Secret Manager page in the Google Cloud Console:
Click Create secret.
Enter a name for your secret.
Under Secret value, add the sender's email account password.
To save your secret, click Create secret.
Give your Cloud Run service account access to your secret:
Go to the IAM page in the Google Cloud Console:
Locate the Compute Engine default service account associated 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.
Open the Secret Manager page in the Google Cloud Console:
Click on your secret name that contains the secret for your sender's email account password.
In the Permissions tab, click Add member.
Add the Compute Engine default service account associated with your project as a member.
Select Secret Manager Secret Accessor permission as the role.
Click Save.
Give your Cloud Run service account permission to read and write to Cloud Storage buckets:
Go to the IAM page in the Google Cloud Console:
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
Click on the pencil icon in the row containing your Compute Engine default service account. You will see the Edit permissions tab.
Click Add another role.
Add the following role:
- Storage Object Viewer
Click Save.
Write a notifier configuration file to configure your SMTP 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 aSUCCESS
status:apiVersion: cloud-build-notifiers/v1 kind: SMTPNotifier metadata: name: example-smtp-notifier spec: notification: filter: build.status == Build.Status.SUCCESS delivery: server: server-host-name port: "port" sender: sender-email from: from-email recipients: - recipient-email # optional: more emails here password: secretRef: smtp-password secrets: - name: smtp-password value: projects/project-id/secrets/secret-name/versions/latest
Where:
server-host-name
is the address of your SMTP server.port
is the port that will handle SMTP requests. This value should be specified as a string.sender-email
is the email address of the sender account that is seen by the specified server-host-name.from-email
is the email address that is seen by recipients.recipient-email
is a list of one or more email addresses to receive messages from the sender.smtp-password
is the configuration variable used in this example to reference the sender's email account password stored in Secret Manager. The variable name you specify here should match thename
field undersecrets
.project-id
is the ID of your Cloud project.secret-name
is the name of your secret that contains the password to the sender's email account.
To view the example, see the notifier configuration file for the SMTP notifier.
For additional fields you can filter by, see the Build resource. For additional filtering examples, see the Using CEL to filter build events.
Upload your notifier configuration file to a Cloud Storage bucket:
If you do not 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.gsutil mb gs://bucket-name/
Upload the notifier configuration file to your bucket:
gsutil 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/smtp:latest \ --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 SMTP notifier,gs://bucket-name/config-file-name
.project-id
is the ID of your 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 theimage
attribute of yourgcloud run deploy
command. Previous image versions and tags can be found in Artifact Registry.Grant Pub/Sub permissions to create authentication tokens in your 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 Cloud project.project-number
is your Cloud project number.
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 RunInvoker
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 Cloud project.
Create the
cloud-builds
topic to receive build update messages for your notifier:gcloud pubsub topics create cloud-builds
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 Cloud project.
Notifications for your Cloud Build project are now set up. The next
time you invoke a build, specified recipients
will receive an email with a
notification if the build matches the filter you've configured.
What's next
- Learn how to configure notifications using the Slack notifier.
- Learn how to configure notifications using the HTTP notifier.
- Learn how to configure notifications using the BigQuery notifier.
- Learn how to subscribe to build notifications.
- Learn how to write a Cloud Build build configuration file.