Configuring HTTP notifications

Cloud Build can notify you of build updates by sending you notifications to desired channels, such as Slack or your SMTP server. This page explains how to configure notifications using the HTTP notifier.

Before you begin

Enable the Cloud Build, Cloud Run, and Pub/Sub APIs.
Enable the APIs

Install the gcloud command-line tool.

Cloud Build notifiers

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

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 the configured service. All notifiers use a common YAML spec for configuration, stored in Cloud Storage.

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
`http`	sends a JSON payload to another HTTP endpoint
`slack`	uses a Slack webhook to post messages to a Slack channel
`smtp`	sends emails via an SMTP server
`bigquery`	pushes build data to a BigQuery instance

Configuring HTTP notifications

The following section explains how you can manually configure HTTP notifications using the HTTP notifier to sent POST requests to a given recipient URL. If you would like to automate the configuration instead, see Automating configuration for notifications.

To configure HTTP notifications:

To use the HTTP notifier to send POST requests to a given recipient URL:

Give your Cloud Run service account permission to read and write to Cloud Storage buckets:
1. Go to the IAM page in the Google Cloud Console:
  
  Open the IAM page
2. Locate the Compute Engine default service account associated with with your project:
  
  Your Compute Engine default service account will look similar to the following:
```
project-number-compute@developer.gserviceaccount.com
```
3. Click on the pencil icon in the row containing your Compute Engine default service account. You will see the Edit permissions tab.
4. Click Add another role.
5. Add the following role:
  - Storage Object Viewer
  Note: If you want to grant permissions at the bucket level instead of the project level, add the Storage Legacy Object Owner role to your bucket when you create one. To learn more, see Project-level roles vs. bucket-level roles.
6. Click Save.
Write a notifier configuration file to configure your HTTP notifier and filter on build events:

In the following example notifier configuration file, the filter field uses Common Expression Language with the available variable, build, to filter build events with a SUCCESS status:
```
apiVersion: cloud-build-notifiers/v1
kind: HTTPNotifier
metadata:
  name: example-http-notifier
spec:
  notification:
    filter: build.status == Build.Status.SUCCESS
    delivery:
      # The `http(s)://` protocol prefix is required.
      url: url
```
Where:
- url is the configuration variable used in this example to specify the URL for your request.
- url is the URL you want to specify as your recipient server.
To view the example, see the notifier configuration file for the HTTP notifier.

For additional fields you can filter by, see the Build resource. For additional filtering examples, see the Filtering builds in notifications.
Upload your notifier configuration file to a Cloud Storage bucket:
1. If you do not have a Cloud Storage bucket, run the following command to create a bucket, where bucket-name is the name you want to give your bucket, subject to naming requirements.
```
gsutil mb gs://bucket-name/
```
2. Upload the notifier configuration file to your bucket:
```
gsutil cp config-file-name gs://bucket-name/config-file-name
```
  Where:
  - bucket-name is the name of your bucket.
  - config-file-name is the name of your notifier config file.
Deploy your notifier to Cloud Run:
```
 gcloud run deploy service-name \
   --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/http:latest \
   --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
```
Where:
- service-name is the name of the Cloud Run service to which you're deploying the image.
- config-path is the path to the configuration file for your HTTP notifier, gs://bucket-name/config-file-name.
- project-id is the ID of your Cloud project.
The gcloud run deploy command pulls the latest version of the hosted image from the Cloud Build-owned Artifact Registry. Cloud Build supports notifier images for nine months. After nine months, Cloud Build deletes the image version. If you would like to use a prior image version, you will need to specify the full semantic version of the image tag in the image attribute of your gcloud run deploy command. Previous image versions and tags can be found in Artifact Registry.

Note: While running this command, you may be prompted to specify additional arguments such as --region or --platform. To learn more about parameters you can pass to the gcloud run deploy command, see Deploying to Cloud Run.

Grant Pub/Sub permissions to create authentication tokens in your project:

 gcloud projects add-iam-policy-binding project-id \
   --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator

Where:

project-id is the ID of your Cloud project.
project-number is your Cloud project number.

Create a service account to represent your Pub/Sub subscription identity:
```
gcloud iam service-accounts create cloud-run-pubsub-invoker \
  --display-name "Cloud Run Pub/Sub Invoker"
```
You can use cloud-run-pubsub-invoker or use a name unique within your Google Cloud project.
Give the cloud-run-pubsub-invoker service account the Cloud Run Invoker permission:
```
gcloud run services add-iam-policy-binding service-name \
   --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
   --role=roles/run.invoker
```
Where:
- service-name is the name of the Cloud Run service to which you're deploying the image.
- project-id is the ID of your Cloud project.
Create the cloud-builds topic to receive build update messages for your notifier:
```
gcloud pubsub topics create cloud-builds
```
Create a Pub/Sub push subscriber for your notifier:
```
 gcloud pubsub subscriptions create subscriber-id \
   --topic=cloud-builds \
   --push-endpoint=service-url \
   --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
```
Where:
- subscriber-id is the name you want to give your subscription.
- service-url is the Cloud Run-generated URL for your new service.
- project-id is the ID of your Cloud project.

Notifications for your Cloud Build project are now set up. The next time you invoke a build, your recipient HTTP server at the given URL will receive JSON payloads that match the Build resource if the build matches the filter you've configured.

What's next

Learn how to configure notifications using the Slack notifier.
Learn how to configure notifications using the SMTP notifier.
Learn how to configure notifications using the BigQuery notifier.
Learn how to subscribe to build notifications.
Learn how to write a Cloud Build build configuration file.