Shape the future of software delivery and make your voice heard by taking the 2021 State of DevOps survey.

Creating webhook triggers

Cloud Build enables you to define webhook triggers, which can authenticate and accept incoming webhook events. These events, sent to a custom URL, allow you to directly connect external systems and external source code management systems such as Bitbucket.com, Bitbucket Server, or GitLab, to Cloud Build through webhook events.

With webhook triggers, you can define an inline build configuration file rather than specify a source when creating your trigger. The inline build configuration enables you to have control over git operations and define the rest of your build.

This page outlines how you can create webhook triggers.

Before you begin

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • To use gcloud commands on this page, install the Cloud SDK.

Creating webhook triggers

Console

To create a webhook trigger using the Google Cloud Console:

  1. Open the Triggers page:

    Open the Build 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: A name for your trigger.
    • Description (Optional): A description for your trigger.
    • Event: Select Webhook event to set up your trigger to start builds in response to incoming webhook events.
    • Webhook URL: Use the webhook URL to authenticate incoming webhook events.

      • Secret: You will need a secret to authenticate incoming webhook events. You can create a new secret or use an existing secret.

        To create a new secret:

        1. Select Create New.
        2. Click Create Secret.

          You will see the Create a webhook secret pop-up box.

        3. In the Secret name field, enter a name for your secret.

        4. Click Create secret to save your secret, which will automatically be created and stored for you in Secret Manager.

        To use an existing secret:

        1. Select Use existing.
        2. In the Secret field, select the name of the secret you want to use from the drop-down menu or follow the instructions to add a secret by resource ID.
        3. In the Secret version field, select your secret version from the drop-down menu.

      After you have created or selected your secret, you will see a Webhook URL preview. Your URL will contain an API key generated by Cloud Build and your secret. If Cloud Build is unable to retrieve your API key, you can manually add your API key to the URL or learn how to obtain an API key if you do not have one yet.

      You can use the URL to invoke a webhook event by making an HTTP request using the POST method.

       https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}
      

      After completing these steps, the Secret Manager Secret Accessor role will automatically be granted to your Cloud Build service account, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. If you do not see this role automatically added to your service account, complete the following steps outlined in Granting Secret Manager role to your service account.

    • Source (optional): Select the repository to build when the webhook trigger runs. If you're specifying an inline build configuration, you're not required to specify the following source.

    • Revision (optional): Select the branch or tag to build when the webhook trigger runs. If you're specifying an inline build configuration, you're not required to specify the following revisions.

      • Branch (optional): Set a trigger to build on this branch. You must specify a literal value. Regular expressions are not supported.
      • Tag (optional): Set a trigger to build on this tag. You must specify a literal value. Regular expressions are not supported.
    • Configuration: Select the build config file located in your remote repository or create an inline build config file to use for your build. If you did not specify a source repository, you must select an Inline build config file as your configuration option.

      • Type: Select the type of configuration to use for your build.
        • Cloud Build configuration file (yaml or json): Use a build config file for your configuration.
        • Dockerfile: Use a Dockerfile for your configuration.
      • Location: Specify the location for your configuration.

        • Repository: If your config file is in located in your remote repository, provide the location of your build config file or the Dockerfile directory and a name for the resulting image. If your configuration is a Dockerfile, you can optionally 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: If you selected Cloud Build configuration file (yaml or json) as your configuration option, you can specify your build config inline. 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.

      In the following example, the inline build config file logs echoes "hello world":

       steps:
       - name: 'ubuntu'
         args: ['echo', 'hello world']
      
    • Substitutions (optional): If you selected the build config file as your build config option or created an inline build config file, you can choose to define trigger-specific substitution variables using this field. You can also obtain data using payload bindings when defining substitution variables values.

    • Filters (optional): You can create a rule within a trigger that determines whether or not your trigger will execute a build based on your substitution variables.

      To see example syntax for filtering you could apply to your webhook triggers, see Using CEL to filter build events.

  5. Click Create to create your build trigger.

gcloud

To create a webhook trigger:

gcloud alpha builds triggers create webhook \
  --name=TRIGGER_NAME \
  --repo=PATH_TO_REPO \
  --secret=PATH_TO_SECRET \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --filter='_SUB_ONE == prod' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Where:

  • TRIGGER_NAME is the name of your trigger.
  • PATH_TO_REPO is the path to the repository to invoke a build on. For example, https://www.github.com/owner/repo.
  • PATH_TO_SECRET is the path to your secret as stored in Secret Manager. For example, projects/my-project/secrets/my-secret/versions/2.
  • PATH_TO_INLINE_BUILD_CONFIG is the path to your inline build config file if you use --inline-config.
  • TAG_NAME is the name of your tag if you want to set your trigger to build on a tag.
  • PATH_TO_BUILD_CONFIG is the path to your build config file if you use --build-config.
  • BRANCH_NAME is the name of your branch if you want to set your trigger to build on a branch.

(Optional) Obtaining an API key

You will need an API key to authenticate your incoming webhook event.

To obtain an API key:

  1. Open the Credentials page in the Google Cloud Console:

    Open the Credentials page

  2. Click Create credentials.

  3. Click API Key.

    You will see a pop-up box with your API key created. Take note of your API key.

  4. If you would like to restrict your key, click Restrict key to complete additional steps to secure your key. Otherwise, click Close.

(Optional) Granting Secret Manager role to your service account

Cloud Build automatically grants the Secret Manager Secret Accessor role to service accounts that require the role during secret configuration. If you do not see this role automatically granted to the necessary service account, complete the following steps to manually add the role so that your service account has access to your secret:

  1. Open the IAM page in the Cloud Console:

    Open the IAM page

  2. Take note of your Cloud Build service account you would like to grant the role to.

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

    Open the Secret Manager page

  4. Click on the name of your secret.

    You will see the Secret details page.

    1. Click on the Permissions tab on the info panel on the right-hand side.

    2. Click on Add member.

    3. In the New Member section, add the member email associated with your Cloud Build service account.

    4. In the Select a role section, select Secret Manager > Secret Manager Secret Accessor.

    5. Click Add.

Using CEL to filter build events

Cloud Build uses CEL with the variable, build, on fields listed in the Build resource to access fields associated with your build event such as your trigger ID, image list, or substitution values. You can use the filter string to filter build events in your build config file using any field listed in the Build resource. To find the exact syntax associated with your field, see the cloudbuild.proto file.

Filtering by trigger ID

To filter by trigger ID, specify the value of your trigger ID in the filter field using build.build_trigger_id, where trigger-id is your trigger ID as a string:

filter: build.build_trigger_id == trigger-id

Filtering by status

To filter by status, specify the build status you want to filter on in the filter field using build.status.

The following example shows how to filter build events with a SUCCESS status using the filter field:

filter: build.status == Build.Status.SUCCESS

You can also filter builds with varying statuses. The following example shows how to filter build events that have a SUCCESS, FAILURE, or TIMEOUT status using the filter field:

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

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

Filtering by tag

To filter by tag, specify the value of your tag in the filter field using build.tags, where tag-name is the name of your tag:

filter: tag-name in build.tags

You can filter based on the number of tags specified in your build event using size. In the following example, the filter field filters build events that have exactly two tags specified with one tag specified as v1:

filter: size(build.tags) == 2 && "v1" in build.tags

Filtering by images

To filter by images, specify the value of your image in the filter field using build.images, where image-name is the full name of your image as listed in Container Registry such as gcr.io/example/image-one:

filter: image-name in build.images

In the following example, the filter filters on build events that have either gcr.io/example/image-one or gcr.io/example/image-two specified as image names:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Filtering by time

You can filter build events based on a build's create time, start time, or finish time by specifying one of the following options in your filter field: build.create_time, build.start_time, or build.finish_time.

In the following example, the filter field uses timestamp to filter build events with a request time to create the build at July 20, 2020 at 6:00 AM:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

You can also filter on build events by time comparisons. In the following example, the filter field uses timestamp to filter build events with a start time between July 20, 2020 at 6:00 AM and July 30, 2020 at 6:00 AM.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

To learn more about how timezones are expressed in CEL, see the language definition for timezones.

To filter by duration of a build, you can use duration to compare timestamps. In the following example, the filter field uses duration to filter build events with a builds that run for at least five minutes:

filter: build.finish_time - build.start_time >= duration("5m")

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"

If you want to filter on strings using regular expressions, you can use the built-in matches function. In the example below, the filter field filters for builds with a status of FAILURE or TIMEOUT and that also have a build substitution variable TAG_NAME with a value that matches the regular expression v{DIGIT}.{DIGIT}.{3 DIGITS}).

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

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

What's next