Creating your own notifier (original) (raw)

Skip to main content

Creating your own notifier

Cloud Build can notify you of updates to your build status by sending you notifications to selected channels. In addition to notifiers maintained by Cloud Build such as Slack or SMTP, you can also use the provided library in thecloud-build-notifiersrepository to create your own notifier.

This page explains how you can create your own notifier.

Before you begin

Setting up

  1. Open a terminal window on your machine.
  2. Clone and navigate into the cloud-build-notifiers repository:
  git clone https://github.com/GoogleCloudPlatform/cloud-build-notifiers.git && cd cloud-build-notifiers
  1. Add a directory for your own notifier and navigate into it, where DIRECTORY_NAMEis the name of your directory:
  mkdir DIRECTORY_NAME && cd DIRECTORY_NAME
  1. Initialize go modules in your new directory, where DIRECTORY_NAMEis the name of your new directory:
  go mod init github.com/GoogleCloudPlatform/cloud-build-notifiers/DIRECTORY_NAME

You should now see a go.mod file in your directory. 5. Add the following line to your go.mod file to ensure you are using the latest version of notifiers: 

 replace github.com/GoogleCloudPlatform/cloud-build-notifiers/lib/notifiers => ../

Your dependencies are now set up and you are ready to create your own notifier.

The cloud-build-notifiers contains a lib/notifiers directory. In thelib/notifiers directory, you will see a file named notifier.go. This file contains the framework you can use to create your own notifier.

You will need to define two methods to create a notifier in your main file.

  1. In the new directory, create a file named main.go.
  2. In main.go, import the notifiers library framework and any other dependencies:
  3. Define a main method for your notifier. In this example, logger is the name of the notifier:
    The main method uses the Main method defined in the notifier.go file, which is used to set up notifier binaries.
  4. Define a struct for your notifier, where you will define the variables for your interface. In this example, logger is the name of the notifier:
  5. Add the notifier functionality. The notifier interface is defined by two methods:
    • SetUp: The SetUp method accepts a configuration, fetches secrets, and pulls specified filters out of the configuration and stores them as a Common Expression Language predicate that can be used to send notifications. To learn more about CEL, see the cel-spec repository.
    • SendNotification: The SendNotification method is what is used to send notifications to your selected channel or service.
      The definition of the notifier is available in notifier.goand in the Go documentation.
      In the following example, the notifier interface is defined using the SetUpand the SendNotification method to print build logs, with loggeras the name of your notifier:
      Your final main.go file should look similar to the following file. In this example, logger is used as the name of the notifier.
      Next, configure your notifier.

Configure notifications

  1. Write a notifier configuration file to configure your notifier and filter on build events:
    In the following example notifier configuration file, the filter field uses CEL with the available variable, build, to filter build events with a SUCCESS status:
    Where:
  2. Upload your notifier configuration file to a Cloud Storage bucket:
    1. If you don't have a Cloud Storage bucket, then run the following command to create a bucket, where BUCKET_NAME is the name you want to give your bucket, subject tonaming requirements.
    gcloud storage buckets create gs://BUCKET_NAME/
    1. 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.

  3. Build and deploy your notifier:
    1. Create a Dockerfile for the logging-sample:
    2. Build and deploy the notifier using the following cloudbuild.yaml file.
      Where:
      • _CONFIG_PATH is the path to your notifier configuration, such as gs://BUCKET_NAME/CONFIG_FILE_NAME.yaml.

To run the cloudbuild.yaml, pass in the notifier path as a substitution variable. 

 gcloud builds submit .  --substitutions=_CONFIG_PATH=gs://BUCKET_NAME/CONFIG_FILE_NAME
  1. 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:

  1. 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. 6. 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:

  1. 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, seePub/Sub topics for build notifications. 8. 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:

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

Test notifications

To test notifications for the example used in this guide, you can invoke a build by running the gcloud builds submit command.

In the following example, we specify success.yaml as the configuration path. Running this command should result in a minimal successful build. You should also be able to see an output of your build logs.

 gcloud builds submit --no-source --config=success.yaml

Where success.yaml is:

 steps:
 - name: busybox
   args: ["true"]

In the following example, we specify failure.yaml as the configuration path. Running this command should result in a failed build. Instead of seeing an output of your build logs, you will see an output informing you that there was no match for the CEL filters you specified in your source.

gcloud builds submit --no-source --config=failure.yaml

Where failure.yaml is:

 steps:
 - name: busybox
   args: ["false"]

If you created a notifier that's configured to perform another task other than logging output to Cloud Run service logs, you can also run the gcloud builds submit command to test your notifications. To examine errors associated with your build, check the Cloud Run logs for your service. To learn more, seeViewing logs in Cloud Run.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-06-12 UTC.