Subscribe to build notifications (original) (raw)

Cloud Build publishes messages on aGoogle 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. Each message contains a base64 JSON string representation of yourBuild resource in themessage.data attribute. The build's unique ID and the build'sstatus 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 theoptions.pubsubTopicfield of your build config file. For more information about configuring topic names in your build config file, seePub/Sub topics for build notifications.

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

Receive 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 lets you receive build notifications from Pub/Sub.
   The service account has the following format, whereproject-number 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 theCloud 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-numberis your project number:

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

1. Select Service Agents > Cloud Build Service Agent as your role.
2. Click Save.
3. Enable the Pub/Sub API:
   Enable the Pub/Sub API
4. 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, seePub/Sub topics for build notifications.
To learn more about managing Pub/Sub topics, seeManaging topics and subscriptions.

Push subscriptions

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 subscriptions

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

You have several options for subscribing to build update notifications. For example, you canpush messages to an endpoint, orwrite 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 aboutPub/Sub Client 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, seeCloud Build notifiers.