Connect to Cloud Build

You can invoke builds automatically using Cloud Build triggers and Secure Source Manager webhooks.

Required roles

To get the permissions that you need to create Cloud Build triggers, ask your administrator to grant you the following IAM roles:

• Cloud Build Editor (roles/cloudbuild.builds.editor) on your project
• Secure Source Manager Repo Admin (roles/securesourcemanager.repoAdmin) on your repository
• Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) on the Secure Source Manager instance

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

For information on granting Secure Source Manager roles, see Access control with IAM and Grant users instance access.

Set up a webhook trigger

Cloud Build uses build triggers to enable CI/CD automation. You can configure triggers to listen for incoming events, such as when a new commit is pushed to a repository or when a pull request is initiated, and then automatically execute a build when new events come in. You can also configure triggers to build code on any changes to your source repository or only on changes that match certain criteria.

To set up a webhook Trigger:

1. Enable and set up Cloud Build in your project.

2. Open the Triggers page in the Google Cloud console.

   Open the Triggers page

3. Select your project from the project selector drop-down menu at the top of the page.

4. Click Open.

5. Click Create trigger.

6. Enter the following trigger settings:

   • Name: enter a name for your trigger.

   • Region: select the region for your trigger. If the build config file associated with your trigger specifies a private pool, the region you select for your trigger must match the region of the private pool.

     Note: If using a private pool, you must assign external IPs to allow your private pool to access the public internet. For more details, see Creating a new private pool.

     If you select global as your region, Cloud Build uses the region specified in your build config file to run your build. This can either be the region of the private pool, if you specify a private pool in your build config file, or the global default pool if you don't specify a private pool.

   • Description (optional): Enter a description for your trigger.

   • Event: Select Webhook event as the repository event to invoke the trigger.

     If Secret Manager is not installed, you are prompted to enable the Secret Manager.

   • Webhook URL: select one of the following:

     • Use a new secret if you want to generate a new secret using Cloud Build. Click Create secret to create your secret.
     • Use an existing secret or create your own if you want to use an existing secret. Enter the secret and version in the drop down selection boxes.

     If you use an existing secret, you might need to manually grant the Secret Manager Secret Accessor role to the Cloud Build service agent [e-mail].

     To learn more, see Granting a role to the Cloud Build service agent.

7. Click Show URL preview and record the URL. You need this URL to set up the webhook in Secure Source Manager.

8. In the Configuration section, for Type select Cloud Build configuration file (YAML or JSON) and for Location, select Inline.

9. Click the Open Editor button to edit your build config file.

   The following example Cloud Build YAML file has steps to clone a repository, print the contents of its README file, and set the _REPO variable to a Secure Source Manager repository my-repo:

   steps:
     # Clone repo
     - name: gcr.io/cloud-builders/git
       args:
         - clone
         - '${_REPO}'
         - .
     # Print the content of README.md
     - name: gcr.io/cloud-builders/git
       args:
         - '-c'
         - cat README.md
       entrypoint: /bin/sh
   substitutions:
     _REPO: https://prod-test-instance-123456789012-git.us-central1.sourcemanager.dev/my-project-id/my-repo.git
   

   Where https://prod-test-instance-123456789012-git.us-central1.sourcemanager.dev/my-project-id/my-repo.git is your HTTPS repository URL found at the top of your repository page.

   Note: If you need to use the git command, use the gcr.io/cloud-builders/git Docker image provided by Cloud Build as your first choice. For other images, you might need to run git config --global credential.'https://*.*.sourcemanager.dev'.helper gcloud.sh to set up the credential helper.

10. Click Create.

Grant the Cloud Build Service account access to Secure Source Manager

Once you have created your trigger, you need to grant the Cloud Build service account access to Secure Source Manager.

1. From the Cloud Build page, navigate to Settings.

   Go to Cloud Build settings

2. Copy the value of the Service account email.

3. In the Secure Source Manager web interface, navigate to the repository you want to give the Cloud Build service account permissions in.

4. Click the Permissions tab.

5. Click Add user.

6. In the Add principal field, enter the Cloud Build service account email address.

7. In the Assign a role drop-down, select Secure Source Manager Repository Reader.

8. Click Save.

9. Assign the Cloud Build service account the securesourcemanager.instanceAccessor role by running the following command:

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:SA_EMAIL \
       --role=roles/securesourcemanager.instanceAccessor
   

   Replace the following:

   • PROJECT_ID with the Secure Source Manager instance project ID.
   • SA_EMAIL with the Cloud Build service account email.

Set up a webhook

1. In the Secure Source Manager web interface, navigate to the repository you want to create a webhook for.
2. Click Settings.
3. Click Webhooks, and then click Add webhook.

4. In the Hook ID field, enter an ID for the webhook.

   Note: Hook IDs must follow the resource naming convention. They must include only lower case letters, numbers, or dashes, must begin with a letter, and cannot be changed after creating the webhook.

5. In the Target URL field, enter the Webhook URL you copied when you set up a webhook trigger in Cloud Build.

6. The Webhook URL contains your key and secret values entered when you created your Cloud Build trigger. To prevent leaking these values, remove them from the end of the target URL and copy to the Sensitive Query String field.

   To locate your key and secret in your webhook URL, look for the text starting with key=

   For example, given the following URL: https://cloudbuild.googleapis.com/v1/projects/my-project/triggers/test-trigger:webhook?key=eitIfKhYnv0LrkdsyHqIros8fbsheKRIslfsdngf&secret=Hello%20Secret%20Manager

   Copy and remove the portion starting with the question mark ?key=... from the Target URL field. Then remove the initial question mark, move the remaining portion key=... to the Sensitive Query String field.

7. In the Trigger on section, select one of the following:

   • Push: to trigger on a push to the repository.
   • Pull request state changed: to trigger on a change in the pull request state.

8. If you selected Push, then you can enter an allowlist for push events in the Branch filter field.

   The Branch filter field uses the glob pattern and only operations on the matched branches will cause a build trigger. If the field is empty or *, then push events for all branches are reported.

9. Click Add webhook.

10. The webhook is displayed in the Webhooks page.

    Note: When you add or edit a webhook, the length of the Sensitive Query String might be inconsistent with the entered one, which is expected as placeholder strings are used to ensure security.

Test your webhook

1. In the Secure Source Manager *Webhooks page, click the webhook you want to test.

2. Go to the bottom of the page and click Test delivery.

   A placeholder event is added to the delivery queue. It might take a few seconds before it shows up in the delivery history.

3. You can also use a git command to push or merge a pull request to test the webhook.

4. In Cloud Build navigate to the History page.

   The build invoked by the test event is displayed.

5. You can view the Request and Response to the test delivery in the Recent deliveries section of the Secure Source Manager webhook page after you send your first test delivery.

Substitute Cloud Build YAML variables with payload data

1. In the Secure Source Manager Webhooks page, in the Recent deliveries section, click the top row.

   The Request header and content sent by the webhook payload is displayed.

2. Navigate to the Cloud Build dashboard, and then click Triggers.

3. Click the trigger you want to configure.

4. In the Advanced section, under Substitution variables, click + Add variable.

5. Enter the name and value of the variable. The value prefix is body.

   For example, to substitute _REPO_URL with the payload data field repository.clone_url and _COMMIT_SHA with latest commit sha in Cloud Build YAML, enter the following names and values:

   • Variable 1: _REPO_URL Value 1: $(body.repository.clone_url)
   • Variable 2: _COMMIT_SHA Value 2: $(body.after)

   The Cloud Build YAML file resembles the following:

   steps:
   - name: gcr.io/cloud-builders/git
     env:
     - '_REPO_URL=$_REPO_URL'
     - '_COMMIT_SHA=$_COMMIT_SHA'
     script: |
       #!/bin/sh
       git clone ${_REPO_URL} /workspace
       cd /workspace
       git reset --hard ${_COMMIT_SHA}
   

What's next

• Learn how to view build results.
• Learn how to troubleshoot build errors.