Configuring Slack notifications

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

Before you begin

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

    Enable the APIs

Cloud Build notifiers

Cloud Build sends all build status 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 pull 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
slack uses a Slack webhook to post messages to a Slack channel
smtp sends emails via an SMTP server
http sends a JSON payload to another HTTP endpoint

Configuring Slack notifications

To configure Slack notifications using the Slack notifier:

  1. Create a Slack app for your desired Slack workspace.

  2. Activate incoming webhooks to post messages from Cloud Build to Slack.

  3. Navigate to your Slack app to locate the URL for the incoming webhook. Your URL will look similar to the following:

    http://hooks.slack.com/services/...
    
  4. Store your incoming webhook URL in Secret Manager:

    1. Open the Secret Manager page in the Google Cloud Console:

      Open the Secret Manager page

    2. Click Create secret.

    3. Enter a name for your secret.

    4. Under Secret value, add your incoming webhook URL for your Slack app.

    5. To save your secret, click Create secret.

  5. Give your Cloud Run service account access to your secret:

    1. Go to the Cloud IAM page in the Google Cloud Console:

      Open the Cloud 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
      

      Take note of your Compute Engine default service account.

    3. Open the Secret Manager page in the Google Cloud Console:

      Open the Secret Manager page

    4. Click on your secret name that contains the secret for your Slack app.

    5. In the Permissions tab, click Add member.

    6. Add the Compute Engine default service account associated with your project as a member.

    7. Select Secret Manager Secret Accessor permission as the role.

    8. Click Save.

  6. Write a notifier configuration file to configure your Slack 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: SlackNotifier
     metadata:
       name: example-slack-notifier
     spec:
       notification:
         filter: build.status == Build.Status.SUCCESS
         delivery:
           webhookUrl:
             secretRef: webhook-url
       secrets:
       - name: webhook-url
         value: projects/project-id/secrets/secret-name/versions/latest
    

    Where:

    • webhook-url is the configuration variable used in this example to reference the Slack webhook URL path stored in Secret Manager. Note: The variable name you specify here should match the name field under secrets.
    • project-id is the ID of your Cloud project.
    • secret-name is the name of your secret that contains your Slack webhook URL.

    To view the example, see the notifier configuration file for the Slack notifier.

    For additional fields you can filter by, see the Build resource. For additional filtering examples, see the Filtering examples section.

  7. 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 configuration file. To see an example configuration file for the Slack notifier, see slack.yaml.example.
  8. Deploy your notifier to Cloud Run:

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/slack:latest \
       --no-allow-unauthenticated \
       --update-env-vars=CONFIG_PATH=config-path
    

    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 Slack notifier, `gs://bucket-name/config-file-name.

    The gcloud run deploy command pulls the latest version of your built image from 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.

  9. 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.
  10. 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.

  11. 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.
  12. 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, you will receive a notification in Slack if the build matches the filter you've configured.

Automating notification configuration for Slack

The cloud-build-notifiers repository contains a setup script, setup.sh, that automates the setup outlined in the Configuring Slack notifications. Before running the script, ensure that you have created a secret for your incoming webhook URL using Secret Manager as outlined in the steps above. To automate notification configuration for Slack, complete the following steps:

  1. Clone the cloud-build-notifiers repository.

  2. Run the following command in the root of the repository:

     ./setup.sh slack config-path secret-name
    

    Where:

    • config-path is the path to your notifiers configuration file.
    • secret-name is the name of your secret stored in Secret Manager.

After running the script, you will see the following message:

** NOTIFIER SETUP COMPLETE **

Your Slack notifier is now set up. You can view the complete script in the cloud-build-notifiers repository or run ./setup.sh --help for usage instructions associated with the script.

Filtering examples

You can filter build events using the filter field in the notifier config file with the available variable, build. The filter field uses Common Expression Language. To learn more, see Common Expression Language. For additional fields you can filter by, see the Build resource.

Filtering by status

To filter by status, specify the status of your build in the filter field using build.status. In the following example, the filter field filters builds that have a SUCCESS or FAILURE status:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE]

To see additional status values you can filter by, see Status under the Build resource reference.

Filtering by trigger ID

To filter by trigger ID, specify the value of your trigger ID in the filter field using with build.build_trigger_id:

filter: build.build_trigger_id == trigger-id

Where:

  • trigger-id is your trigger ID as a string.

Filtering by tag

To filter by tag, specify the value of your tag in the filter field using with build.tags:

filter: tag-name in build.tags

Where:

  • tag-name is the name of your tag.

Filtering by substitution

You can filter by substitution by specifying the substitution variable in the filter field using build.substitutions. In the following example, the filter field lists builds that contain the substitution variable substitution-variable and checks if the substitution-variable matches the specified substitution-value:

filter: build.substitutions[substitution-variable] == substitution-value

Where:

  • substitution-variable is the name of your substitution variable.
  • substitution-value is the name of your substitution value.

You can also filter by default substitution variable values. In the following example, the filter field lists builds that have the branch name master and builds that have the repository name github.com/user/my-example-repo. The default substitution variables BRANCH_NAME and REPO_NAME are passed in as keys to the build.substitutions:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

To see a list of default substitution values, see Using default substitutions.

What's next