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](https://docs.cloud.google.com/build/docs/subscribe-build-notifications#push)
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](https://docs.cloud.google.com/build/docs/subscribe-build-notifications) 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](https://docs.cloud.google.com/build/images/cloud-build-notifiers.svg)

## 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](https://docs.cloud.google.com/pubsub/docs/create-topic) to
receive build notifications. In your build config file, the
[`options.pubsubTopic`](https://docs.cloud.google.com/build/docs/build-config-file-schema#pubsub-topic)
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.

> [!WARNING]
> **Warning:** We strongly recommend using different topics for [Pub/Sub](https://docs.cloud.google.com/build/docs/automate-builds-pubsub-events?generation=2nd-gen) triggers and build notifications. Otherwise, notifications might turn into trigger events again, resulting in a recurring cycle of notifications and trigger events.

**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](http://github.com/GoogleCloudPlatform/cloud-build-notifiers). 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:

- [Configure BigQuery notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-bigquery)
- [Configure GitHub Issues notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-githubissues)
- [Configure Google Chat notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-googlechat)
- [Configure HTTP notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-http)
- [Configure Slack notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-slack)
- [Configure SMTP notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-smtp)

## Automate notification configuration

Cloud Build provides a [setup script](https://github.com/GoogleCloudPlatform/cloud-build-notifiers/blob/master/setup.sh)
that you can use to automate notification configuration for
[Cloud Build supported notifiers](https://docs.cloud.google.com/build/docs/configuring-notifications/notifiers#supported_notifiers).

To learn how to configure notifications for
[Cloud Build supported notifiers](https://docs.cloud.google.com/build/docs/configuring-notifications/notifiers),
see [Automating configuration for notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/automate).

## Create your own notifier

In addition to notifiers maintained by Cloud Build,
such as [Slack](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-slack)
or [SMTP](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-smtp),
you can use the provided library in the [`cloud-build-notifiers` repository](http://github.com/GoogleCloudPlatform/cloud-build-notifiers) to create your own notifier.

To learn how to create your own notifier, see [Creating your own notifier](https://docs.cloud.google.com/build/docs/configuring-notifications/create-notifier).

## What's next

- Learn how to configure [BigQuery](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-bigquery), [GitHub Issue](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-githubissues), [Google Chat](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-googlechat), [HTTP](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-http), [Slack](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-slack), or [SMTP](https://docs.cloud.google.com/build/docs/configuring-notifications/configure-smtp) notifiers.
- Learn how to [automate configuration for
  notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/automate).
- Learn how to [create your own notifier](https://docs.cloud.google.com/build/docs/configuring-notifications/create-notifier).