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.

      • 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 \
       --subtitutions=\
         _SUB_ONE='$(body.message.test)', _SUB_TWO='$(body.message.output)'
       --filter='_SUB_ONE == prod'
       --build-config=PATH_TO_BUILD_CONFIG # or --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --tag=TAG_NAME  # or --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_BUILD_CONFIG is is the path to your build config file.
  • PATH_TO_INLINE_BUILD_CONFIG is the path to your inline build config file.
  • 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.

(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.

What's next