Cloud Build enables you to configure triggers that do not immediately execute a build but instead mark a build as pending until approved. If a user with permissions approves a pending build, the build will start. If the approval is denied, the build will not start.
This page explains how you can manually approve or reject builds. To learn how to configure a trigger that requires approval, see Creating a build trigger.
Before you begin
-
Enable the Cloud Build API.
Install Google Cloud CLI.
If you have not already, create a build trigger configured to require approval.
Granting permissions
If a user has the Cloud Build Editor role, the user has permissions to update a trigger to require or not require approval. To learn more about Cloud Build permissions, see IAM and permissions. In order to grant a user permission to approve builds within your project, the user must have the Cloud Build Approver role.
To add the Cloud Build Approver role:
Open the IAM page in the Google Cloud console.
Click Grant access.
You will see the Grant access panel.
In the Add principals section, add users to give them permission to grant approval for pending builds within your project.
You must add one or more principals in this section. If you add yourself as a principal, note that you will still need to manually approve a pending build if your trigger is gated by an approval.
In the Assign roles section, select Cloud Build > Cloud Build Approver.
The users you specified now have access to approve or reject pending builds.
Approving builds
Console
To approve a pending build in the Google Cloud console:
Open the Cloud Build Dashboard page in the Google Cloud console.
If you have builds to approve, you will see a message at the top of the page with the number of builds awaiting your approval. To the right of the message, click View Builds to view the list of builds awaiting your approval.
Click on the checkboxes of the builds you'd like to approve. You can select multiple builds to approve or one individual build to approve.
At the top of the page, click Approve to approve your selected builds.
Before the build starts, you will see the Approve build dialog box. In the dialog box, you can add an optional message and a URL to be displayed along with the build's approval. To include a URL, click Show additional options to enter a URL.
In the dialog box, click Approve to approve the build.
Once you approve, the build will start immediately. If the organization
policy
(constraints/cloudbuild.allowedIntegrations
) denies access to
the connected repository, the policy will
override the approval. To learn more, see Gate builds on organization policy.
gcloud
To approve a pending build using gcloud commands
, run the following command
in your terminal window:
gcloud builds approve BUILD_ID \
--project=PROJECT_ID \
--url=URL \
--comment=COMMENT
Replace the placeholder values in the above commands with the following:
BUILD_ID
is the ID of the build you'd like to approve.PROJECT_ID
is your project ID.- [Optional]
URL
is the URL containing information about the approval, such as a link to a JIRA ticket. - [Optional]
COMMENT
is the message you want displayed upon approval of the build.
Once you approve, the build will start immediately. If the organization
policy to define builds for allowed integrations
(constraints/cloudbuild.allowedIntegrations
) is set, the policy will
override the approval. To learn more, see Applying organization
policy to build triggers.
Rejecting builds
Console
To reject a pending build in the Google Cloud console:
Open the Cloud Build Dashboard page in the Google Cloud console.
If you have builds to approve, you will see a message at the top of the page with the number of builds awaiting your approval. To the right of the message, click View Builds to view the list of builds awaiting your approval.
You can select multiple builds to reject or one individual build to reject. Click on the checkboxes of the builds you'd like to reject.
Click Reject at the top of the page to reject the build.
If you reject a build, the build will not start.
gcloud
To reject a pending build using gcloud commands
, run the following command
in your terminal window:
gcloud builds reject BUILD_ID \
--project=PROJECT_ID \
--url=URL \
--comment=COMMENT
Replace the placeholder values in the above commands with the following:
BUILD_ID
is the ID of the build you'd like to reject.PROJECT_ID
is your project ID.- [Optional]
URL
is the URL containing information about the rejection, such as a link to a JIRA ticket. - [Optional]
COMMENT
is the message you want displayed upon rejection of the build.
If you reject a build, the build will never start.
Receiving notifications for builds waiting for approval
You can use Cloud Build notifiers to receive notifications about pending builds using a Cloud Build maintained notifier, such as Slack or SMTP server, or by creating your own notifier.
To configure notifications:
Follow the instructions on one of following pages to configure notifications for your desired service:
When configuring notifications using one of the pages above, you must configure your notifier to filter builds with a PENDING status. This will send you notifications on builds waiting for approval. In the following example SMTP notifier configuration file, the filter field uses Common Expression Language (CEL) to filter build events with a PENDING status:
apiVersion: cloud-build-notifiers/v1 kind: SMTPNotifier metadata: name: example-smtp-notifier spec: notification: filter: build.status == Build.Status.PENDING delivery: server: example.gmail.com port: 0000 sender: sender@example.com ...
To view the full example, see the notifier configuration file for the SMTP notifier.
To deploy your notifier, run the
gcloud run
command in your terminal. The following example deploys the SMTP notifier using Cloud Run.gcloud run deploy example.gmail.com \ --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/smtp:latest \ --update-env-vars=CONFIG_PATH=smtp.yaml, PROJECT_ID=my-project
You should now receive notifications for pending builds to your service.
What's next
- Learn how to create and manage build triggers.
- Learn how to view build results for build triggers