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 in general and external SCMs in particular such as Bitbucket.com, Bitbucket Server, or GitLab, to Cloud Build through events without the need to write custom integrations or extensive code.

With webhook triggers, you can specify an inline build configuration file so you can easily set up integrations and have control over git clone operations in 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

Obtaining an API key

Before creating a webhook trigger, you will need an API key to authenticate your incoming webhook event.

To obtain an API key:

  1. Open the Credentials page in the 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. You can use this key by passing key=API_KEY into your application as described below.

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

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: After entering your credentials, use the webhook URL below and the API key you initially set up 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 preview of your webhook URL. 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.

    • Revision (optional): Select the branch or tag to build when the webhook trigger runs.

      • Branch (optional): Set a trigger to build on this branch. You must specify a literal value. Regular expressions are not currently supported.
      • Tag (optional): Set a trigger to build on this tag. You must specify a literal value. Regular expressions are not currently 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, you will need to run the gcloud alpha command:

     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) 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