Cloud Build publishes messages on a
[Google Pub/Sub](https://docs.cloud.google.com/pubsub) topic when your build's state changes,
such as when your build is created, when your build transitions to a working
state, and when your build completes. Each
[message](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/PubsubMessage) contains a base64 JSON
string representation of your
[Build resource](https://docs.cloud.google.com/build/docs/api/reference/rest/v1/projects.builds) in the
`message.data` attribute. The build's unique ID and the build's
[status](https://docs.cloud.google.com/build/docs/api/reference/rest/v1/projects.builds#status) can be found
in the `message.attributes` field.

By default, messages are published to the `cloud-builds` topic; you can also
specify a custom topic name in the
[`options.pubsubTopic`](https://docs.cloud.google.com/build/docs/build-config-file-schema#pubsub-topic)
field of your build config file. For more information about configuring topic
names in your build config file, see
[Pub/Sub topics for build notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/notifiers#pubsub-topic-config).

You can use a [push or pull model](https://docs.cloud.google.com/pubsub/docs/subscriber#push_pull) for your
Pub/Sub subscriptions.

## Receive build notifications

To receive build notifications:

1. Enable the Cloud Build API:

   [Enable the Cloud Build API](https://console.cloud.google.com/apis/library/cloudbuild.googleapis.com)

   [In most cases](https://docs.cloud.google.com/service-usage/docs/troubleshooting#service-agent-not-found),
   when you enable the Cloud Build API, the **Cloud Build Service
   Agent** service account is automatically added to your project. The
   service account lets you receive build notifications from
   Pub/Sub.

   The service account has the following format, where
   <var translate="no">project-number</var> is your project number:

        service-project-number@gcp-sa-cloudbuild.iam.gserviceaccount.com

   If you don't see the **Cloud Build Service Agent** service account on your
   IAM page, or you can't receive notifications from
   Pub/Sub, then follow these steps to add the
   **Cloud Build Service Agent** service account to your project:
   1. Open the **IAM** page in the Google Cloud console:

      [Open the IAM page](https://console.cloud.google.com/iam-admin/iam)
   2. Click **Grant access**.

   3. Add the following principal, where <var translate="no">project-number</var>
      is your project number:

          service-project-number@gcp-sa-cloudbuild.iam.gserviceaccount.com

      > [!NOTE]
      > **Note:** Occasionally, the service agent might not be listed as an available principal. If this occurs, you might need to [manually create the service agent](https://docs.cloud.google.com/iam/docs/create-service-agents).

   4. Select **Service Agents** \> **Cloud Build Service Agent** as your role.

   5. Click **Save**.

2. Enable the Pub/Sub API:

   [Enable the Pub/Sub API](https://console.cloud.google.com/apis/library/pubsub.googleapis.com)
3. Create the `cloud-builds` topic:

       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, see
   [Pub/Sub topics for build notifications](https://docs.cloud.google.com/build/docs/configuring-notifications/notifiers#pubsub-topic-config).

   To learn more about managing Pub/Sub topics, see
   [Managing topics and subscriptions](https://docs.cloud.google.com/pubsub/docs/admin).

> [!NOTE]
> **Note:** Pub/Sub notifications generated by Cloud Build are subject to the [Pub/Sub Service Level Agreement (SLA)](https://cloud.google.com/pubsub/sla).

## Push subscriptions

[Push subscriptions](https://docs.cloud.google.com/pubsub/docs/push) deliver messages to an HTTP endpoint
that you define. Messages are delivered as soon as they are published to the
topic.

Messages sent from push subscriptions look like this:

    {
      "message": {
        "attributes": {
          "buildId": "abcd-efgh...",
          "status": "SUCCESS"
        },
        "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
        "messageId": "136969346945"
      },
      "subscription": "projects/myproject/subscriptions/mysubscription"
    }

## Pull subscriptions

[Pull subscriptions](https://docs.cloud.google.com/pubsub/docs/pull) deliver message when polled by the
subscribed application. Messages are delivered when the subscription is polled.

Messages sent from pull subscriptions look like this:

    {
      "receivedMessages": [
        {
          "ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
          "message": {
            "attributes": {
              "buildId": "abcd-efgh-...",
              "status": "SUCCESS"
            },
            "data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
            "messageId": "19917247034"
          }
        }
      ]
    }

## Subscribe to build update notifications

You have several options for subscribing to build update notifications.
For example, you can
[push messages to an endpoint](https://docs.cloud.google.com/pubsub/docs/push#configuring-http-endpoints),
or
[write a Python app for polling your subscription](https://docs.cloud.google.com/pubsub/docs/pull#pubsub-pull-python).

To learn how to set up Pub/Sub subscriptions for build updates,
read the [Pub/Sub Subscriber Guide](https://docs.cloud.google.com/pubsub/docs/subscriber).
You can also learn about
[Pub/Sub Client Libraries](https://docs.cloud.google.com/pubsub/docs/reference/libraries),
which make developing subscriber applications easier.

To learn how to use Pub/Sub to send build updates to
email or to services such as Slack, see
[Cloud Build notifiers](https://docs.cloud.google.com/build/docs/configuring-notifications/notifiers).