Creating Pub/Sub triggers

Cloud Build Pub/Sub triggers enable you to execute builds in response to Google Cloud events published over Pub/Sub. You can use information from a Pub/Sub event to parameterize your build and to decide if a build should execute in response to the event. Pub/Sub triggers can be configured to listen to any Pub/Sub topic.

This page explains how you can create a Pub/Sub trigger to invoke builds in response to events on Artifact Registry, Container Registry, and Cloud Storage.

Before you begin

  • Enable the Cloud Build API.

    Enable the API

  • Make sure your source code contains a build config file or a Dockerfile in the repository.
  • To use gcloud commands on this page, install the Cloud SDK.

Creating a build trigger that responds to Artifact Registry events

You can create a Pub/Sub trigger that responds to Artifact Registry events such as when images are pushed, tagged, or deleted. This section discusses how you can create a Pub/Sub trigger that invokes a build when a new tag is pushed to an existing image. If you are unfamiliar with Artifact Registry, see the Artifact management overview.

Console

To create a trigger that listens for a new tag pushed to an existing image in Artifact Registry using the Google Cloud Console:

  1. Open the Triggers page:

    Open the Triggers page

  2. Select your project from the top of the page and click Open.

  3. Click Create trigger.

  4. Enter the following trigger settings:

    • Name: Enter a name for your trigger.
    • Description (Optional): Enter a description for your trigger.
    • Event: Select Pub/Sub message as the event to invoke your trigger.
    • Subscription: Select the Pub/Sub topic you would like to subscribe to as the trigger event. You see all existing topics in your project in the drop-down menu.

    • Source: Select the repository to build when the trigger runs.

    • Revision: Select the branch or tag to build when the trigger runs.

      • Branch: Enter the name of the branch to invoke your build on.
      • Tag: Enter the name of the tag to invoke your build on.
    • Configuration: Select the build config file (located in your remote repository) or create an inline build config file to use for your build.

      • Cloud Build configuration file (yaml or json): Use a build config file for your configuration. You'll need to provide the location of your build config file and optionally substitution variables that you want to use.

      • Dockerfile: Use a Dockerfile for your configuration. You'll need to specify the Dockerfile directory and a name for the resulting image. Optionally, you can also provide a timeout for your build. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute.

      • Inline: Use an inline build config for your configuration. Click Open Editor to write your build config file in the Google Cloud Console using YAML or JSON syntax. Click Done to save your build config.

    • Substitutions (optional): If you selected the build config file as your build config option, you can choose to define trigger-specific substitution variables using this field.

      In the following example, we want to obtain the name of the image tag from the payload and the action associated with the gcr event. To do so, create substitution variables using payload bindings.

      Specify the following variables and values below:

      Variable Name Variable Value
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message references the PubSubMessage published by publishers and consumed by subscribers. To see more examples of the Pub/Sub notification payload, see Notification examples.

    • Filters (optional): You can create filters within a trigger that determine whether or not your trigger will execute a build in response to the incoming payload by specifying filters on substitution variables. The filter expression must evaluate to true in order for a build to execute.

      We recommend using filtering when setting up Pub/Sub triggers on topics with several messages. Filters can be used to precisely control builds that are executed in response to incoming Pub/Sub messages. To learn about risks associated with setting up a trigger without filters, see Risks associated with an unfiltered trigger.

      In the following example, we want the trigger to execute a build if a new tag is pushed to an existing image. We use filter condition operators to check if the _IMAGE_TAG variable matches an existing tag name and if the _ACTION variable matches INSERT to look for newly added data.

      Specify the following as your filters:

      • _IMAGE_TAG != ""
      • _ACTION == INSERT

      Filtering syntax in Pub/Sub triggers use Common Expression Language (CEL) for expression evaluation. To learn more about CEL, see the cel-spec repository. To see more example syntax for filtering you could apply to your Pub/Sub triggers, see Filtering builds.

  1. Click Create to create your build trigger
  2. .

gcloud

To create a trigger that listens for a new tag pushed to an existing image in Artifact Registry using the gcloud commands:

  1. Open a terminal window.
  2. Run the gcloud alpha command to create a build trigger in your project. In the example below, the trigger is configured to respond to builds with a tag matching prod and an action matching INSERT based on the specified payload as defined by the substitution variable, _IMAGE_TAG.

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Where:

    • TRIGGER_NAME is the name of your trigger.
    • PROJECT_ID is the ID of your Cloud project.
    • TOPIC_NAME is the name of Pub/Sub topic you've subscribed to.
    • BUILD_CONFIG is the path to your build config file.
    • INLINE_BUILD_CONFIG is the path to your inline build config file.
    • REPO_NAME is the name of the source repository the build is invoked on.
    • TAG_NAME is the name of your tag if you want to set your trigger to build on a tag.
    • BRANCH_NAME is the name of your branch if you want to set your trigger to build on a branch.

Creating a build trigger that responds to Container Registry events

You can create a Pub/Sub trigger that responds to Container Registry events such as when images are pushed, tagged, or deleted. This section discusses how you can create a Pub/Sub trigger that invokes a build when an image matches a tag set up by a custom filter. If you are unfamiliar with Container Registry, see the Quickstart for Container Registry to learn how to push and pull images with tags.

Console

To create a trigger that listens for an image push in Container Registry and matches based on a tag name using the Google Cloud Console:

  1. Open the Triggers page:

    Open the Triggers page

  2. Select your project from the top of the page and click Open.

  3. Click Create trigger.

  4. Enter the following trigger settings:

    • Name: Enter a name for your trigger.
    • Description (Optional): Enter a description for your trigger.
    • Event: Select Pub/Sub message as the event to invoke your trigger.
    • Subscription: Select the Pub/Sub topic you would like to subscribe to as the trigger event. You see all existing topics in your project in the drop-down menu.

    • Source: Select the repository to build when the trigger runs.

    • Revision: Select the branch or tag to build when the trigger runs.

      • Branch: Enter the name of the branch to invoke your build on.
      • Tag: Enter the name of the tag to invoke your build on.
    • Configuration: Select the build config file (located in your remote repository) or create an inline build config file to use for your build.

      • Cloud Build configuration file (yaml or json): Use a build config file for your configuration. You'll need to provide the location of your build config file and optionally substitution variables that you want to use.

      • Dockerfile: Use a Dockerfile for your configuration. You'll need to specify the Dockerfile directory and a name for the resulting image. Optionally, you can also provide a timeout for your build. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute.

      • Inline: Use an inline build config for your configuration. Click Open Editor to write your build config file in the Google Cloud Console using YAML or JSON syntax. Click Done to save your build config.

    • Substitutions (optional): If you selected the build config file as your build config option, you can choose to define trigger-specific substitution variables using this field.

      In the following example, we want to obtain the name of the image tag from the payload and the action associated with the gcr event. To do so, create substitution variables using payload bindings.

      Specify the following variables and values below:

      Variable Name Variable Value
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message references the PubSubMessage published by publishers and consumed by subscribers. To see more examples of the Pub/Sub notification payload, see Notification examples.

    • Filters (optional): You can create filters within a trigger that determine whether or not your trigger will execute a build in response to the incoming payload by specifying filters on substitution variables. The filter expression must evaluate to true in order for a build to execute.

      We recommend using filtering when setting up Pub/Sub triggers on topics with several messages. Filters can be used to precisely control builds that are executed in response to incoming Pub/Sub messages. To learn about risks associated with setting up a trigger without filters, see Risks associated with an unfiltered trigger.

      In the following example, we want the trigger to execute a build if the name of the _IMAGE_TAG tag variable matches a specific tag name, such as prod. You can specify your filter condition operator as "==" for exact matching. You can also check for the action associated with your gcr event as well. For example, you may want to specify _ACTION is INSERT to look for newly added data.

      Specify the following as your filters:

      • _IMAGE_TAG == prod
      • _ACTION == INSERT

      Filtering syntax in Pub/Sub triggers use Common Expression Language (CEL) for expression evaluation. To learn more about CEL, see the cel-spec repository. To see more example syntax for filtering you could apply to your Pub/Sub triggers, see Filtering builds.

  1. Click Create to create your build trigger
  2. .

gcloud

To create a trigger that listens for an image push in Container Registry and matches based on a tag name using gcloud commands:

  1. Open a terminal window.
  2. Run the gcloud alpha command to create a build trigger in your project. In the example below, the trigger is configured to respond to builds with a tag matching prod and an action matching INSERT based on the specified payload as defined by the substitution variable, _IMAGE_TAG.

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "prod" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Where:

    • TRIGGER_NAME is the name of your trigger.
    • PROJECT_ID is the ID of your Cloud project.
    • TOPIC_NAME is the name of Pub/Sub topic you've subscribed to.
    • BUILD_CONFIG is the path to your build config file.
    • INLINE_BUILD_CONFIG is the path to your inline build config file.
    • REPO_NAME is the name of the source repository the build is invoked on.
    • TAG_NAME is the name of your tag if you want to set your trigger to build on a tag.
    • BRANCH_NAME is the name of your branch if you want to set your trigger to build on a branch.

Creating a build trigger that responds to Cloud Storage events

You can create a Pub/Sub trigger that responds to Cloud Storage events such as when a new binary is pushed to an existing storage bucket. This section discusses how you can create a Pub/Sub trigger that responds with a build when deploying a new binary to an uploaded bucket. If you are unfamiliar with Cloud Storage, see the Quickstarts.

Console

To create a trigger that listens to Cloud Storage events using the Google Cloud Console:

  1. Open the Triggers page:

    Open the Triggers page

  2. Select your project from the top of the page and click Open.

  3. Click Create trigger.

  4. Enter the following trigger settings:

    • Name: Enter a name for your trigger.
    • Description (Optional): Enter a description for your trigger.
    • Event: Select Pub/Sub message as the event to invoke your trigger.
    • Subscription: Select the Pub/Sub topic you would like to subscribe to as the trigger event. You see all existing topics in your project in the drop-down menu.

    • Source: Select the repository to build when the trigger runs.

    • Revision: Select the branch or tag to build when the trigger runs.

      • Branch: Enter the name of the branch to invoke your build on.
      • Tag: Enter the name of the tag to invoke your build on.
    • Configuration: Select the build config file (located in your remote repository) or create an inline build config file to use for your build.

      • Cloud Build configuration file (yaml or json): Use a build config file for your configuration. You'll need to provide the location of your build config file and optionally substitution variables that you want to use.

      • Dockerfile: Use a Dockerfile for your configuration. You'll need to specify the Dockerfile directory and a name for the resulting image. Optionally, you can also provide a timeout for your build. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute.

      • Inline: Use an inline build config for your configuration. Click Open Editor to write your build config file in the Google Cloud Console using YAML or JSON syntax. Click Done to save your build config.

    • Substitutions (optional): If you selected the build config file as your build config option, you can choose to define trigger-specific substitution variables using this field.

      In this example, we want to watch for the deployment of a new binary when it is uploaded to a bucket. To obtain this data, we can create substitution variables using payload bindings.

      Specify the following variables and values below:

      Variable Name Variable Value
      _EVENT_TYPE $(body.message.attributes.eventType)
      _BUCKET_ID $(body.message.attributes.bucketId)
      _OBJECT_ID $(body.message.attributes.objectId)

      body.message references the PubSubMessage published by publishers and consumed by subscribers. To see more examples of the Pub/Sub notification payload, see Notification examples.

    • Filters (optional): You can create filters within a trigger that determine whether or not your trigger will execute a build in response to the incoming payload by specifying filters on substitution variables. The filter expression must evaluate to true in order for a build to execute.

      We recommend using filtering when setting up Pub/Sub triggers on topics with several messages. Filters can be used to precisely control builds that are executed in response to incoming Pub/Sub messages. To learn about risks associated with setting up a trigger without filters, see Risks associated with an unfiltered trigger.

      Since we want the trigger to execute a build if the new binary has been deployed to a specific bucket, we can use "==" operator to check for exact matches. You can also use the "matches" keyword if you want to match by regular expression.

      Specify the following as your filters:

      • _EVENT_TYPE == OBJECT_FINALIZE
      • _OBJECT_ID matches ^<object-id>$
      • _BUCKET_ID matches ^<bucket-id>$
  1. Click Create to create your build trigger
  2. .

gcloud

To create a build trigger that listens to build events with a specific event type in Cloud Storage:

  1. Open a terminal window.
  2. Run the gcloud alpha command to create a build trigger in your project. In the example below, the trigger is configured to respond to builds with a Cloud Storage event associated with a new binary pushed to an existing storage bucket:

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --subtitutions=\
         _EVENT_TYPE='$(body.message.attributes.eventType)'
         _BUCKET_ID='$(body.message.attributes.bucketId)'
         _OBJECT_ID='$(body.message.attributes.objectId)'
       --filter='_EVENT_TYPE == "OBJECT_FINALIZE" && _OBJECT_ID.matches("<object-id>") && _BUCKET_ID.matches("<bucket-id>")'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    Where:

    • TRIGGER_NAME is the name of your trigger.
    • PROJECT_ID is the ID of your Cloud project.
    • TOPIC_NAME is the name of Pub/Sub topic you've subscribed to.
    • BUILD_CONFIG is the path to your build config file.
    • INLINE_BUILD_CONFIG is the path to your inline build config file.
    • REPO_NAME is the name of the source repository the build is invoked on.
    • TAG_NAME is the name of your tag if you want to set your trigger to build on a tag.
    • BRANCH_NAME is the name of your branch if you want to set your trigger to build on a branch.

Risks associated with an unfiltered trigger

If you have not configured filters on your Pub/Sub trigger, your trigger may end up invoking an infinite number of builds if your trigger modifies an artifact or object which unintentionally publishes a new message to the topic it's listening to. For example, your trigger may invoke an infinite number of builds if your trigger:

  • Points to a gcr topic.
  • Creates any image or tag in gcr.
  • Points to a gcs topic for a specific object in your bucket and modifies that object.

If you encounter an infinite loop, you can delete your trigger or update it to point to a separate topic to avoid incurring additional charges for each build you invoke.

What's next