GCP for DevOps — Build Triggers

2 minute read

Build Triggers

Build triggers connect your Git repository to Cloud Build, automatically starting builds when code is pushed, a pull request is opened, or a tag is created.

Supported Source Repositories

  • Cloud Source Repositories — Google-hosted Git
  • GitHub — via Cloud Build GitHub app
  • GitHub Enterprise
  • Bitbucket Cloud — via Cloud Build connection
  • GitLab — via Cloud Build connection

Create a Push Trigger

# Connect a GitHub repository first
$ gcloud builds connections create github my-github-conn \
    --region=us-central1

# Create a trigger for pushes to main branch
$ gcloud builds triggers create github \
    --name=deploy-on-push \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --branch-pattern="^main$" \
    --build-config=cloudbuild.yaml

# Create a trigger for any branch push
$ gcloud builds triggers create github \
    --name=ci-all-branches \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --branch-pattern=".*" \
    --build-config=cloudbuild.yaml

Tag-Based Trigger

# Trigger on semantic version tags (v1.0.0, v2.1.3, etc.)
$ gcloud builds triggers create github \
    --name=release-on-tag \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --tag-pattern="^v[0-9]+\.[0-9]+\.[0-9]+$" \
    --build-config=cloudbuild-release.yaml

Pull Request Trigger

# Trigger on pull requests to main (for CI checks)
$ gcloud builds triggers create github \
    --name=pr-check \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --pull-request-pattern="^main$" \
    --build-config=cloudbuild-pr.yaml \
    --comment-control=COMMENTS_ENABLED_FOR_EXTERNAL_CONTRIBUTORS_ONLY

Trigger with Substitutions

# Pass custom variables to the build
$ gcloud builds triggers create github \
    --name=deploy-staging \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --branch-pattern="^develop$" \
    --build-config=cloudbuild.yaml \
    --substitutions=_ENV=staging,_REGION=us-central1

Included/Excluded Files

Only trigger builds when specific files change.

# Only build when source code changes (not docs)
$ gcloud builds triggers create github \
    --name=build-on-src-change \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --branch-pattern="^main$" \
    --build-config=cloudbuild.yaml \
    --included-files="src/**,Dockerfile,package.json" \
    --ignored-files="docs/**,*.md,LICENSE"

Manage Triggers

# List all triggers
$ gcloud builds triggers list --region=us-central1

NAME              CREATE_TIME               STATUS
deploy-on-push    2026-03-30T10:00:00Z      ENABLED
ci-all-branches   2026-03-30T10:01:00Z      ENABLED
release-on-tag    2026-03-30T10:02:00Z      ENABLED

# Describe a trigger
$ gcloud builds triggers describe deploy-on-push --region=us-central1

# Run a trigger manually
$ gcloud builds triggers run deploy-on-push \
    --region=us-central1 \
    --branch=main

# Disable a trigger
$ gcloud builds triggers update deploy-on-push \
    --region=us-central1 \
    --no-require-approval \
    --disabled

# Delete a trigger
$ gcloud builds triggers delete ci-all-branches --region=us-central1

Approval-Required Triggers

Require manual approval before a build proceeds.

$ gcloud builds triggers create github \
    --name=deploy-production \
    --repository=projects/my-project/locations/us-central1/connections/my-github-conn/repositories/my-repo \
    --branch-pattern="^main$" \
    --build-config=cloudbuild-prod.yaml \
    --require-approval

Pub/Sub Notifications

Get notified when builds succeed or fail.

# Create a Pub/Sub topic for build events
$ gcloud pubsub topics create cloud-build-events

# Cloud Build automatically publishes to:
# projects/PROJECT_ID/topics/cloud-builds
# Filter and forward:
$ gcloud pubsub subscriptions create build-alerts \
    --topic=cloud-builds \
    --push-endpoint=https://my-webhook.example.com/build-events

Trigger Types Comparison

Trigger Type Use Case When It Fires
Push to branch CI on every commit git push to matching branch
Pull request PR validation PR opened/updated to target branch
Tag Release builds git tag v1.0.0 && git push --tags
Manual On-demand gcloud builds triggers run
Pub/Sub External events Message on a Pub/Sub topic
Webhook External systems HTTP POST to webhook URL

Common Mistakes

Mistake Why It’s Wrong Fix
No branch pattern filter Triggers on all branches Use --branch-pattern="^main$"
Missing --ignored-files Builds on doc-only changes Exclude *.md, docs/**
No approval on prod triggers Accidental prod deploys Use --require-approval
Single trigger for all environments Can’t control per-env Separate triggers per environment
Not monitoring build notifications Missed failures Set up Pub/Sub + alerting

Quick Reference

Command Description
gcloud builds triggers create github Create a trigger
gcloud builds triggers list List triggers
gcloud builds triggers run NAME --branch=B Manual trigger
gcloud builds triggers update NAME --disabled Disable trigger
gcloud builds triggers delete NAME Delete trigger

Next → Artifact Registry

Updated:

You may also enjoy