Cloud Build notifiers

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 a configured service, such as Slack or an SMTP server.

This page provides an overview of Cloud Build notifiers.

Cloud Build notifiers

Cloud Build sends all build event updates, along with build metadata, to Pub/Sub on either the cloud-builds topic or a user-defined topic. Cloud Build notifiers can be configured to listen to that topic, filter the messages it receives, and send messages to your service through Cloud Run.

All notifiers use a common YAML spec for configuration, stored in Cloud Storage. If your chosen service requires authentication, then its credentials are stored in Secret Manager. Cloud Run routes your message and sends your notifications to your service.

The following diagram shows how Cloud Build interacts with other Google Cloud products, such as Pub/Sub and Cloud Run, to send notifications:

Diagram for Cloud Build notifiers

Pub/Sub topics for build notifications

By default, Cloud Build sends build notifications to a Pub/Sub topic named cloud-builds if one exists. You can also create a custom Pub/Sub topic to receive build notifications. In your build config file, the options.pubsubTopic field defines the name of the topic that Cloud Build sends notifications to:

  • If options.pubsubTopic is left blank, then Cloud Build uses a default value of cloud-builds as the topic name for builds from that file. As a result, if you create a cloud-builds topic and leave options.pubsubTopic undefined in all your build config files, then that topic receives all your build notifications.

  • If you specify a custom topic name in options.pubsubTopic, then Cloud Build sends notifications for that build config file to that topic. Custom topic names are useful when you don't want all of your build notifications published to the same topic.

    When you use a custom topic name in a build config file, you must also assign the roles/pubsub.publisher role to any service account other than the default Cloud Build service account.

Publish build notifications to Pub/Sub topics across projects

To publish build notifications to a Pub/Sub topic in a different project from where the build was executed, provide the roles/pubsub.publisher role to the service account in the target project.

For example, you have Project A and Project B. You execute a build in Project A using Service Account A, and you want to publish build notifications to a Pub/Sub topic in Project B. To do so, you could grant Service Account A the roles/pubsub.publisher role in Project B by running the following command:

  gcloud projects add-iam-policy-binding ProjectB --member 'serviceAccount:ServiceAccountA' --role 'roles/pubsub.publisher'

You could then use a build config such as the following, which lets you execute a build in Project A and publish build notifications to Project B:

  steps:
    - name: ubuntu
      args:
        - pwd
  serviceAccount: projects/ProjectA/serviceAccounts/ServiceAccountA
  options:
    pubsubTopic: projects/ProjectB/topics/CustomTopic
    logging: desired-logging-option

Supported notifiers provided by Cloud Build

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
githubissues uses a GitHub webhook to create issues against a GitHub repository
googlechat uses a Google Chat webhook to post messages to a Google Chat space
http sends a JSON payload to another HTTP endpoint
slack uses a Slack webhook to post messages to a Slack channel
smtp sends emails through an SMTP server

To learn more about how to configure each notifier, see the corresponding page for each service:

Automate notification configuration

Cloud Build provides a setup script that you can use to automate notification configuration for Cloud Build supported notifiers.

To learn how to configure notifications for Cloud Build supported notifiers, see Automating configuration for notifications.

Create your own notifier

In addition to notifiers maintained by Cloud Build, such as Slack or SMTP, you can use the provided library in the cloud-build-notifiers repository to create your own notifier.

To learn how to create your own notifier, see Creating your own notifier.

What's next