Automating configuration for notifications

You can configure Cloud Build to send you build notifications to Slack, Google Chat, an SMTP server, an HTTP endpoint, or a BigQuery instance using Cloud Build notifiers. This page explains how you can automate the configuration process for your desired notifier.

Automating notification configuration

Cloud Build provides a setup script that you can use to automate notification configuration. To configure notifications using the setup script:

Slack

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

Enable the APIs

Obtaining and storing credentials

  1. Create a Slack app for the Slack workspace to which you want to send notifications.

  2. Activate incoming webhooks to post messages from Cloud Build to Slack.

  3. Navigate to your Slack app to locate the URL for the incoming webhook. Your URL will look similar to the following:

    http://hooks.slack.com/services/...

  4. 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 Slack app.

    5. To save your secret, click Create secret.

Writing a notifier configuration file

Write a notifier configuration file to configure your Slack 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: SlackNotifier
  metadata:
    name: example-slack-notifier
  spec:
    notification:
      filter: build.status == Build.Status.SUCCESS
      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

Where:

  • webhook-url is the configuration variable used in this example to reference the Slack 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 Slack webhook URL.
  • The uri field references the slack.json file. This file contains a JSON template hosted on Cloud Storage and represents your notification message to your Slack space.

To view the example, see the notifier configuration file for the Slack notifier.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

    ./setup.sh slack config-path -t template-path -s secret-name

Where:

  • config-path is the path to your notifiers configuration file.
  • template-path is the path to your notifiers template file. Your notifiers template file contains the JSON template hoted on Cloud Storage and represents your notification message. You can include your notifiers template file as a path using this variable or within the uri field of your notifiers configuration file.

  • secret-name is the name of your secret stored in Secret Manager.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

SMTP

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

Enable the APIs

Storing credentials

  1. Store the sender's email account password in Secret Manager:

  2. Open the Secret Manager page in the Google Cloud console:

    Open the Secret Manager page

  3. Click Create secret.

  4. Enter a name for your secret.

  5. Under Secret value, add the sender's email account password.

  6. To save your secret, click Create secret.

Writing a notifier configuration file

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 a SUCCESS 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
      template:
        type: golang
        uri: gs:example-gcs-bucket/smtp.html
   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 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 the password to the sender's email account.
  • The uri field references the smtp.html file. This files refers to a html template hosted on Cloud Storage and represents your notification email.

To view the example, see the notifier configuration file for the SMTP notifier.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

    ./setup.sh smtp config-path -t template-path -s secret-name

Where:

  • config-path is the path to your notifiers configuration file.
  • template-path is the path to your notifiers template file. Your notifiers template file contains the JSON template hoted on Cloud Storage and represents your notification message. You can include your notifiers template file as a path using this variable or within the uri field of your notifiers configuration file.

  • secret-name is the name of your secret stored in Secret Manager.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

BigQuery

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs.

Enable the APIs

Granting permissions

Give your Cloud Run service account permission to create and write BigQuery tables and permission to fetch Artifact Registry data related to your build:

  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, where project-number is your project number:

        project-number[email protected]

  3. Click on the pencil icon in the row containing your Compute Engine default service account.

    You will see the Edit access tab.

    1. Click Add another role.

    2. Add the following roles:

      • Artifact Registry Reader

      • BigQuery Data Editor

        The Artifact Registry Reader role enables you to fetch data for your images. The BigQuery Data Editor gives you read and write access to your data.

    3. Click Save.

Writing a notifier configuration file

Write a notifier configuration file to configure your BigQuery notifier and filter on build events:

In the following example notifier config file, the filter field uses Common Expression Language with the variable, build, to filter build events with a specified trigger ID:

 apiVersion: cloud-build-notifiers/v1
 kind: BigQueryNotifier
 metadata:
   name: example-bigquery-notifier
 spec:
   notification:
     filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
     delivery:
       table: projects/project-id/datasets/dataset-name/tables/table-name
     template:
       type: golang
       uri: gs://example-gcs-bucket/bq.json

Where:

  • project-id is the ID of your Google Cloud project.
  • dataset-name is the name you want to give your dataset.
  • table-name is the name you want to give your table.

The table-name in your notifier config file can refer to:

  • a nonexistent table
  • an empty table without a schema

  • an existing table with a schema that matches the schema specifications in the BigQuery notifier

  • The uri field references the bq.json file. This file refers to a JSON template hosted on Cloud Storage and represents the information to insert into your bigquery table.

To view the example, see the notifier config file for the BigQuery notifier.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

     ./setup.sh bigquery -t config-path -t template-path

    Where:

    • config-path is the path to your notifiers configuration file.
    • template-path is the path to your notifiers template file. Your notifiers template file contains the JSON template hoted on Cloud Storage and represents your notification message. You can include your notifiers template file as a path using this variable or within the uri field of your notifiers configuration file.

    After running the script, you will see the following message:

    ** NOTIFIER SETUP COMPLETE **

    Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

HTTP

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Cloud Run, and Pub/Sub APIs.

Enable the APIs

Writing a notifier configuration file

Write a notifier configuration file to configure your HTTP 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: HTTPNotifier
    metadata:
      name: example-http-notifier
    spec:
      notification:
        filter: build.status == Build.Status.SUCCESS
        delivery:
          # The `http(s)://` protocol prefix is required.
          url: url
        template:
          type: golang
          uri: gs://example-gcs-bucket/http.json

Where:

  • url is the configuration variable used in this example to specify the URL for your request.
  • url is the URL you want to specify as your recipient server.
  • The uri field references the http.json file. This file refers to a JSON template hosted on Cloud Storage and represents the json payload to the webhook endpoint.

To view the example, see the notifier configuration file for the HTTP notifier.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

     ./setup.sh http -t config-path

    Where:

    • config-path is the path to your notifiers configuration file.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

Google Chat

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

Enable the APIs

Obtaining and storing credentials

  1. Create a space in Google Chat.

  2. 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/...

  3. 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.

Writing a notifier configuration file

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.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

./setup.sh googlechat config-path -s secret-name

Where:

  • config-path is the path to your notifiers configuration file.
  • secret-name is the name of your secret stored in Secret Manager.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

GitHub Issues

Setting up

The following sections describe steps you need to complete before automating notification configuration for your notifier.

Enabling APIs

Enable the Cloud Build, Compute Engine, Cloud Run, Pub/Sub, and Secret Manager APIs.

Enable the APIs

Obtaining and storing credentials

  1. Create a GitHub Personal Access Token:

    1. Go to the GitHub settings for creating a new token.

    2. Select the repo scope.

    3. Click Generate token

  2. Store your token 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 GitHub token.

    5. To save your secret, click Create secret.

Writing a template configuration file

Write a template configuration file to describe the format created GitHub Issues should take:

In the following example template configuration file, the title and body fields use substitution variables from the build: 

{
    "title": "Build {{.Build.BuildTriggerId}}: {{.Build.Status}}",
    "body": "[{{.Build.ProjectId}}] {{.Build.BuildTriggerId}} status: **{{.Build.Status}}**\n\n[View Logs]({{.Build.LogUrl}})"
}

To view the example, see the template configuration file for the GitHub Issues notifier.

Additional fields can be set from the available body parameters from the GitHub API endpoint for creating an issue.

Writing a notifier configuration file

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: GitHubIssuesNotifier
metadata:
  name: example-githubissues-notifier
spec:
  notification:
    filter: build.status == Build.Status.FAILURE
    template: 
      type: golang
      uri: gs://project-id-notifiers-config/template-file-name
    delivery:
      githubToken:
        secretRef: github-token
      githubRepo: myuser/myrepo
  secrets:
  - name: github-token
    value: projects/project-id/secrets/secret-name/versions/latest

Where:

  • githubToken is the configuration variable used in this example to reference the GitHub token stored in Secret Manager. The variable name you specify here should match the name field under secrets.
  • project-id-notifiers-config is the location where your template will be uploaded, and the bucket will be created if it doesn't already exist.
  • template-file-name is the name of your template file.
  • myuser/myrepo is the name of the repo that issues will be created against.
  • project-id is the ID of your Google Cloud project.
  • secret-name is the name of your secret that contains your GitHub token.

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 the Using CEL to filter build events.

Running the automation script

To automate notification configuration for your notifier:

  1. Clone the cloud-build-notifiers repository.

  2. Configure the Google Cloud CLI with your project ID and region: 

    gcloud config set project project-id
gcloud config set run/region region

    Where:

    • project-id is your Google Cloud project ID.
    • region is the region to deploy the notifier.

  3. Run the following command in the root of the repository:

    ./setup.sh githubissues config-path -t template-path -s secret-name

Where:

  • config-path is the path to your notifiers configuration file.
  • template-path is the path to your notifiers template file. Your notifiers template file contains the JSON template hoted on Cloud Storage and represents your notification message. You can include your notifiers template file as a path using this variable or within the uri field of your notifiers configuration file.

  • secret-name is the name of your secret stored in Secret Manager.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

What's next