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:
Enable and set up Cloud Build in your project.
Open the Triggers page in the Google Cloud console.
Select your project from the project selector drop-down menu at the top of the page.
Click Open.
Click Create trigger.
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.
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
service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com
.To learn more, see Granting a role to the Cloud Build service agent.
Click Show URL preview and record the URL. You need this URL to set up the webhook in Secure Source Manager.
In the Configuration section, for Type select Cloud Build configuration file (YAML or JSON) and for Location, select Inline.
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 repositorymy-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.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.
From the Cloud Build page, navigate to Settings.
Copy the value of the Service account email.
In the Secure Source Manager web interface, navigate to the repository you want to give the Cloud Build service account permissions in.
Click the Permissions tab.
Click Add user.
In the Add principal field, enter the Cloud Build service account email address.
In the Assign a role drop-down, select Secure Source Manager Repository Reader.
Click Save.
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
- In the Secure Source Manager web interface, navigate to the repository you want to create a webhook for.
- Click Settings.
- Click Webhooks, and then click Add webhook.
In the Hook ID field, enter an ID for the webhook.
In the Target URL field, enter the Webhook URL you copied when you set up a webhook trigger in Cloud Build.
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 portionkey=...
to the Sensitive Query String field.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.
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.Click Add webhook.
The webhook is displayed in the Webhooks page.
Test your webhook
- In the Secure Source Manager *Webhooks page, click the webhook you want to test.
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.
You can also use a
git
command to push or merge a pull request to test the webhook.In Cloud Build navigate to the History page.
The build invoked by the test event is displayed.
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
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.
Navigate to the Cloud Build dashboard, and then click Triggers.
Click the trigger you want to configure.
In the Advanced section, under Substitution variables, click + Add variable.
Enter the name and value of the variable. The value prefix is
body
.For example, to substitute
_REPO_URL
with the payload data fieldrepository.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}
- Variable 1:
What's next
- Learn how to view build results.
- Learn how to troubleshoot build errors.