Gate builds on approval

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.
Enable the API

Install Google Cloud CLI.

Note: If you've already installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.
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.

Open the IAM page
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.

Open the Cloud Build Dashboard page
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.

Open the Cloud Build Dashboard page
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