Subscribing to build notifications

Cloud Build publishes messages on a Google Pub/Sub 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.

The Pub/Sub topic to which Cloud Build publishes these build update messages is called cloud-builds. Each message contains a base64 JSON string representation of your Build resource in the message.data attribute. The build's unique ID and the build's status can be found in the message.attributes field.

You can use a push or pull model for your Pub/Sub subscriptions.

Receiving build notifications

To receive build notifications:

1. Enable the Cloud Build API:

   Enable the Cloud Build API

   When you enable the Cloud Build API, the Cloud Build Service Agent service account is automatically added to your project. The service account enables you to receive build notifications via Pub/Sub.

   The service account has the following format, where project-number is your project number:

    [e-mail]
   

   If you do not see the Cloud Build Service Agent service account on your IAM page or are not able to receive notifications via Pub/Sub, 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

   2. Click Grant access.

   3. Add the following principal, where project-number is your project number:

      [e-mail]
      

   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

3. Create the cloud-builds topic:

   gcloud pubsub topics create cloud-builds
   

   To learn more about managing Pub/Sub topics, see Managing topics and subscriptions.

Note: Pub/Sub notifications generated by Cloud Build are subject to the Pub/Sub Service Level Agreement (SLA).

Push

Push subscriptions 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==",
    "message_id": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Pull

Pull subscriptions 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"
      }
    }
  ]
}

How do I subscribe to build update notifications?

You have a variety of options for subscribing to build update notifications. For example, you can push messages to an endpoint, or write a Python app for polling your subscription.

To learn how to set up Pub/Sub subscriptions for build updates, read the Pub/Sub Subscriber Guide. You can also learn about Pub/Sub Client Libraries, which make developing subscriber applications easier.

To learn how to use Pub/Sub to send build updates to services such as Slack or via email, see Cloud Build notifiers.