google/cloud-build-basics — references/cb-run-trigger.md

name: cb-run-trigger description: Manually executes a predefined Cloud Build trigger to start a build. Supports specifying a Git branch, tag, or commit SHA for source-based triggers, and overriding substitution variables for all trigger types.

Table of Contents

• Preconditions (Lines 19-38)
• Inputs (Lines 40-62)
• Execution Steps (Lines 64-132)
  • Step 1: Set Project Context (Lines 66-72)
  • Step 2: Run the Cloud Build Trigger (Lines 74-114)
  • Step 3: Verify Build Initiation and Monitor Status (Lines 116-132)
• Outputs (Lines 134-143)
• Related Skills (Lines 145-151)

Preconditions

• The Cloud Build API (cloudbuild.googleapis.com) must be enabled in the project.

• The user must have the roles/cloudbuild.builds.editor IAM role to initiate builds.

• If the trigger is configured with a user-managed service account, the user must also have the roles/iam.serviceAccountUser permission on that service account (iam.serviceAccounts.actAs).

• Authenticate the gcloud CLI:

  gcloud auth login
  gcloud auth application-default login
  

• Identify the target Google Cloud Project ID. If not known, prompt the user for it.

Inputs

[!IMPORTANT] Pricing: Trigger invocation is free ($0.00). However, the resulting build consumes compute resources. Cloud Build provides 120 free build-minutes per day on default machine types. Beyond this, standard per-minute rates apply based on the machine type and region.

[!WARNING] Substitution Immutability: You can only override values for substitution variables that are ALREADY defined in the trigger configuration. You cannot add new keys at runtime.

[!NOTE] Jurisdictional Constraints: In Jurisdictional Consoles (DRZ), triggers using legacy 1st-gen repositories are disabled for manual runs. Only 2nd-gen repositories are supported.

Execution steps

Step 1: Set the project context

Ensure the gcloud CLI is pointing to the correct project.

gcloud config set project <PROJECT_ID>

Step 2: Run the Cloud Build trigger

Choose the appropriate variation based on the trigger configuration and desired revision.

Variation A: Run using a branch Use this for triggers targeting a specific Git branch.

gcloud builds triggers run <TRIGGER_ID> --region=<REGION> --branch=<BRANCH_NAME>

Variation B: Run using a tag Use this for triggers targeting a specific Git tag.

gcloud builds triggers run <TRIGGER_ID> --region=<REGION> --tag=<TAG_NAME>

Variation C: Run using a commit SHA Use this to build a specific commit hash (short or full 40-character hex SHA).

gcloud builds triggers run <TRIGGER_ID> --region=<REGION> --sha=<COMMIT_SHA>

Variation D: Run with substitution overrides Append the --substitutions flag to any run command to override variables.

gcloud builds triggers run <TRIGGER_ID> --region=<REGION> --branch=<BRANCH_NAME> --substitutions="\_VARIABLE_NAME=<VALUE>"

Variation E: Run a repoless or inline trigger For Manual, Pub/Sub, or Webhook triggers that use an inline cloudbuild.yaml and no repository.

gcloud builds triggers run <TRIGGER_ID> --region=<REGION>

Step 3: Verify build initiation and monitor status

The run command will output a build ID. Use this ID to check the status or view the execution logs.

Check build status:

gcloud builds describe <BUILD_ID> --region=<REGION>

Stream build logs:

gcloud builds log <BUILD_ID> --region=<REGION>

Outputs

Related skills

• cb-create-trigger: Create a new build trigger from a repository or inline source.
• cb-list-triggers: List and filter all triggers in a project and region.
• cb-approve-build: Approve a pending build for triggers requiring manual approval.