Google Cloud Build Monitor

Monitor, analyze, and diagnose Google Cloud Build executions using the gcloud CLI. Provide continuous status updates until builds complete, with detailed failure analysis when builds fail.

Prerequisites

Ensure the gcloud CLI is installed and authenticated:

gcloud auth list
gcloud config get-value project

If not authenticated, inform the user and provide authentication guidance.

Core Workflow

Step 1: Identify the GCP Project

Determine which GCP project contains the build:

Check current default project:
```
gcloud config get-value project
```

If context suggests a specific environment (staging, production, dev), look for matching projects:

gcloud projects list --format="table(projectId,name)" --filter="projectId~staging OR name~staging"

If multiple projects exist and the correct one is unclear, list available projects and ask the user:
```
gcloud projects list --format="table(projectId,name)"
```
Context clues for project selection:
- Branch name "staging" or "main" → look for staging/production projects
- Recent merge to main → likely production build
- PR context → likely staging or CI project

Step 2: Find the Build

Locate the specific build to monitor:

List recent builds:

gcloud builds list --project=PROJECT_ID --limit=10 --format="table(id,status,createTime,source.repoSource.branchName,substitutions.TRIGGER_NAME)"

Find in-progress builds:

gcloud builds list --project=PROJECT_ID --filter="status=WORKING OR status=QUEUED" --format="table(id,status,createTime,source.repoSource.branchName)"

Find builds by branch:

gcloud builds list --project=PROJECT_ID --filter="source.repoSource.branchName=BRANCH_NAME" --limit=5

Build identification strategy:

If user specifies build ID → use that directly
If user mentions "latest" or "current" → find most recent or in-progress build
If user mentions environment (staging, production) → filter by relevant branch/trigger
If PR context available → check GitHub PR checks for Cloud Build link, or find builds matching the commit SHA
If only one build is running → use that one
If multiple builds and ambiguous → show list and ask user to choose

Step 3: Get Build Details

Retrieve comprehensive build information:

gcloud builds describe BUILD_ID --project=PROJECT_ID --format=json

Key fields to extract:

status: QUEUED, WORKING, SUCCESS, FAILURE, CANCELLED, TIMEOUT
steps: Array of build steps with individual status
source: Where the build came from (branch, commit, trigger)
createTime, startTime, finishTime: Timing information
logUrl: Link to Cloud Console logs
substitutions: Build variables including trigger name

Step 4: Monitor Until Complete

Polling behavior:

Poll every 60 seconds
Continue until status is SUCCESS, FAILURE, CANCELLED, or TIMEOUT
Never give up—some builds take an hour or more

Progress updates:

Show initial status with build details
On each poll, report current status
Every 5 minutes, print a reminder that monitoring continues
On step completion, note which step finished

Status interpretation:

QUEUED: Build waiting to start → continue polling
WORKING: Build in progress → continue polling
SUCCESS: Build completed successfully → announce completion
FAILURE: Build failed → analyze failure
CANCELLED: Build was cancelled → report cancellation
TIMEOUT: Build exceeded time limit → report timeout

Step 5: Analyze Failures

When a build fails, provide actionable diagnosis:

Identify failed step:

gcloud builds describe BUILD_ID --project=PROJECT_ID --format="json(steps)"

Parse the steps array to find which step has status: FAILURE.

Get step logs:

gcloud builds log BUILD_ID --project=PROJECT_ID --stream

For specific step logs, look at the log output around the failed step's execution time.

Failure analysis checklist:

Which step failed? (name and index)
What was the step trying to do?
What error message appeared in logs?
Common failure patterns:
- Test failures → look for test output
- Build errors → look for compiler/bundler errors
- Deployment errors → look for permission or resource issues
- Timeout → step exceeded time limit

Report format for failures:

❌ BUILD FAILED - PROJECT_ID

Build ID: BUILD_ID
Duration: X minutes
Failed Step: step-name (step N of M)

Error Summary:
[Extracted error message or description]

Log URL: [logUrl from build details]

Recommended Actions:
[Suggestions based on error type]

Step 6: Completion Notification

On success:

✅ BUILD SUCCEEDED - PROJECT_ID

Build ID: BUILD_ID
Duration: X minutes
Branch: branch-name

All steps completed successfully.

Audio announcement (macOS):

command -v say >/dev/null 2>&1

If say is available, announce completion with a human-friendly message:

Success: say "Cloud Build for [branch or trigger name] completed successfully"
Failure: say "Cloud Build for [branch or trigger name] failed"

Important: Never include the build UUID in the spoken announcement—use the branch name, trigger name, or environment name instead for human-friendly audio.

GitHub Integration

When working in a GitHub PR context:

Find build from PR checks: If the PR has Cloud Build checks, the check details may include the build ID or a link to Cloud Console.

gh pr checks PR_NUMBER --json name,state,detailsUrl

Look for checks with "Cloud Build" in the name or detailsUrl pointing to console.cloud.google.com.

Find build from commit SHA:

gcloud builds list --project=PROJECT_ID --filter="substitutions.COMMIT_SHA=SHA" --limit=1

Error Handling

Authentication errors:

Check gcloud auth list for active account
Suggest gcloud auth login if needed

Permission errors:

Verify project access with gcloud projects describe PROJECT_ID
Suggest checking IAM roles if access denied

Network/API errors:

Wait 60 seconds and retry
After 3 consecutive errors, inform user but continue trying
Never stop monitoring due to transient errors

Proactive Monitoring

Offer to monitor builds in these situations:

After user merges a PR
After user mentions deploying to staging/production
After user pushes to a tracked branch
When user asks about deployment status

Example: "I notice you just merged to main. Would you like me to monitor the production build?"

Key Points

Never give up: Keep polling until definitive completion
Human-friendly audio: Use branch/trigger names, not UUIDs in say command
Context awareness: Infer project and build from conversation context
Actionable failures: Don't just report failure—diagnose and suggest fixes
60-second interval: Balance responsiveness with API considerations
Graceful errors: Transient failures don't stop monitoring

gcb-monitor