Automate builds in response to webhook events

1st gen 2nd gen

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 to automate builds in response to webhook events.

Note: If you are creating a trigger that automates builds on repository events, we recommend using Cloud Build repository triggers. Repository triggers that use Cloud Build repositories (2nd gen) can be configured programmatically and are natively integrated with source providers, currently with support for GitHub and GitLab. Cloud Build repositories (2nd gen) also manage authentication tokens and information on your behalf using Secret Manager. Repository triggers allow for easy filtering of incoming events and post build status back to the source provider, and can also be configured to work with a private network. To learn more, see the Repositories overview page.

Before you begin

• Enable the Cloud Build and Secret Manager APIs.

  Enable the APIs

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

  Note: If you've installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.

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.

   • Region: Select the region for your trigger.

     • If the build config file associated with the trigger specifies a private pool, Cloud Build uses the private pool to run your build. In this case, the region you specify in your trigger must match the region where you created your private pool.
     • If the build config file associated with the trigger does not specify a private pool, Cloud Build uses the default pool to run your build in the same region as 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. This secret is separate from the secret associated with your SSH key.

       To create a new secret:

       1. Select Use a new secret (generated by Cloud Build).

       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 an existing secret or create your own.
       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.

       If you use an existing secret, you may need to manually grant the Secret Manager Secret Accessor role to your Cloud Build service account, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. To learn more, see Granting Secret Manager role to your service account.

     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.

     Use the following command to invoke a webhook event:

     curl -X POST -H "Content-type: application/json" "https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/triggers/${TRIGGER_NAME}:webhook&?key=${API_KEY}secret=&${SECRET_VALUE}trigger=&${TRIGGER_NAME}projectId=${PROJECT_ID}" -d "{}"
     

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

   • Source (optional): Select the source to build when the webhook trigger runs. If you're specifying an inline build configuration, you're not required to specify the following source. You can specify 1st generation or 2nd generation as your source. To learn more, see Cloud Build repositories.

     Note: The region of your repository must match the region of your trigger.

     • Repository: From the list of available repositories, select the desired repository.

     • Branch or Tag: Specify a regular expression with the branch or tag value to match. For information on acceptable regular expression syntax, see RE2 syntax.

     • Comment control: If you selected Pull request (GitHub App only) as your Event, choose one of the following options to control whether a build will automatically be executed by the trigger:

       Warning: Any user with read access to the repository can submit a pull request, which may execute a build that includes changes to the source code in the pull request. To disable this behavior, we recommend using manual approvals to gate builds when making pull requests on public repositories. You can also learn more about the build-time privileges of triggers.

       • Required except for owners and collaborators: When a pull request is created or updated by a repository owner or collaborator, builds will automatically be executed by the trigger. If an external contributor initiates the action, builds will only be executed after an owner or collaborator comments /gcbrun on the pull request.

       • Required: When a pull request is created or updated by any contributor, builds will only be executed after an owner or collaborator comments /gcbrun on the pull request. Builds are executed each time a change to a pull request is made.

       • Not required: When a pull request is created or updated by any contributor, builds will automatically be executed by triggers.

   • 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.
       • Buildpacks: Use buildpacks for your configuration.

     • Location: Specify the location for your configuration.

       • Repository: If your config file is located in your remote repository, provide the location of your build config file, the Dockerfile directory, or the buildpacks directory. If your build config type is a Dockerfile or a buildpack, you will need to provide a name for the resulting image and optionally, a timeout for your build. When you've provided the Dockerfile or buildpack image name, you'll see a preview of the docker build or pack command that your build will execute.
       • Buildpack environment variables (optional): If you selected buildpacks as your configuration type, click Add pack environment variable to specify your buildpack environment variables and values. To learn more about buildpack environment variables, see Environment variables.

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

         Note: Inline build configuration support is not available for Dockerfile or buildpacks.

     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.

5. Click Create to create your build trigger.

gcloud

Preview — Webhook triggers: Cloud Build repositories (2nd gen) support

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. You can process personal data for this feature as outlined in the Cloud Data Processing Addendum, subject to the obligations and restrictions described in the agreement under which you access Google Cloud. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

To create a webhook trigger:

gcloud builds triggers create webhook \
  --region=REGION \
  --name=TRIGGER_NAME \
  --repository=projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME \
  --secret=projects/PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION \
  --substitutions=_SUB_ONE='$(body.message.test)',_SUB_TWO='$(body.message.output)' \
  --subscription-filter='_SUB_ONE == "prod"' \
  --inline-config=PATH_TO_INLINE_BUILD_CONFIG \
  --tag=TAG_NAME
  # --build-config=PATH_TO_BUILD_CONFIG \
  # --branch=BRANCH_NAME

Where:

• REGION is the region for your trigger.
• TRIGGER_NAME is the name of your trigger.
• PROJECT_ID is your Cloud project ID.
• CONNECTION_NAME is the name of your host connection.
• REPO_NAME is the name of your repository.
• SECRET_NAME is the name of your secret as stored in Secret Manager.
• SECRET_VERSION is the version associated with your secret as stored in Secret Manager.
• 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

To authenticate your incoming webhook event, you need an API key.

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 dialog with your API key created. Take note of your API key.

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

   To learn how to restrict your key, see Applying API key restrictions.

(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 Google Cloud console:

   Open the IAM page

2. Optional: To see Google-provided accounts, select the Include Google-provided role grants checkbox.

3. Take note of the build service account you would like to grant the role to.

4. Open the Secret Manager page in the Google Cloud console:

   Open the Secret Manager page

5. Click on the name of your secret.

   You will see the Secret details page.

   1. Click on the Permissions tab.

   2. Click on Grant access.

      You will see the Grant access panel.

   3. In the Add Principals section, add the email associated with the build service account.

   4. In the Assign roles section, select Secret Manager > Secret Manager Secret Accessor.

   5. Click Save.

What's next

• Learn how to create and manage triggers.
• Learn how to build repositories hosted on on Bitbucket Server.
• Learn how to start builds manually.
• Learn how to view build results.
• Learn how to troubleshoot build errors.