cloud-build-investigation

name	cloud-build-investigation
description	🏗️ | Expert-level SRE skill for Google Cloud Build (GCB) and Cloud Run investigations. Activate when user mentions Cloud Build failures, deployment issues to Cloud Run, or needs help debugging GCB pipelines. Specializes in correlating git commits with build failures, analyzing build logs, and providing systematic debugging workflows.
metadata	{"version":"0.1.0"}
compatibility	Gemini CLI

Cloud Build Investigation Skill

This skill provides expert-level SRE capabilities for investigating and debugging Google Cloud Build (GCB) issues, particularly for deployments to Cloud Run.

When to Activate

Use this skill when:

• User mentions Cloud Build failures or errors
• Debugging deployment issues to Cloud Run
• Investigating why a build/deployment stopped working
• Correlating git commits with build failures
• Setting up or troubleshooting Cloud Build pipelines
• Adding environment variables to Cloud Build/Cloud Run

Core Principles

⚠️ CRITICAL: Assume positive intention!

• If a cloudbuild.yaml exists with a trigger, DO NOT MOVE OR MAJORLY CHANGE IT
• The user (likely Riccardo) may have spent hours making it work
• Take baby steps and minimize mutations
• Changing folder targets or major refactoring will likely break things further

Investigation Workflow

Step 1: Gather Build History

1. Run just git-logs-timestamped to get compact commit history with timestamps (YYYYMMDD HH:MM)
2. Run just cloud-build-list to get recent Cloud Builds
3. Identify N successful builds and M failed builds
4. Focus on the FIRST failing build (this is key!)

Step 2: Analyze the Failure

1. Use just cloud-build-show-log FIRST_FAILING_BUILD_ID to examine logs
2. Cross-correlate with git commits via timestamps
3. Cross-reference with the VERSION file (Carlessian standard)
4. Identify the exact commit that introduced the failure

Step 3: Root Cause Analysis

Cross-correlate failed build logs with the git diff of the culprit commit:

• Was it a Dockerfile change?
• A dependency update (Gemfile/requirements.txt/package.json)?
• A configuration change?
• An environment variable issue?

Step 4: Corrective Action

If investigation shows NO errors → Done! ✅

If errors found:

1. File GitHub Issue:

   • Title: [failed Cloud Build] <BUILD_ID> <SHORT_DESCRIPTION>
   • BUILD_ID in title enables deduplication
   • Post the git log list (enables GH to link commits visually)

2. Investigate & Propose Fix:

   • Document findings in the issue
   • Propose a fix with user collaboration

3. Test with Baby Steps:

   • Cloud Build tests require small commit/pushes
   • Version bumps: 1.2.3 → 1.2.3a → 1.2.3b (for quick testing)
   • Each build takes 5-6 minutes
   • Consider combining with minor UI/UX improvements for time efficiency

4. Monitor:

   • Keep checking build status every 2 minutes
   • Use just cloud-build-list and just cloud-build-show-log {{build_id}}

Required Justfile Targets

Ensure the project's justfile has these targets (adapt PROJECT_ID and CLOUD_RUN_ENDPOINT):

# List latest 10 CB builds, possibly the first might still be running
cloud-build-list:
    gcloud builds list --project=PROJECT_ID --limit=10

# Show the log of a specific Cloud Build, eg 7c82188e-485a-4735-a70d-fb303fbfe5a0
cloud-build-show-log build_id:
    @echo "Showing log for build ID: {{build_id}}. Use --stream to follow the log indefinitely (you can do it, but I want Gemini NOT to do it)."
    gcloud builds log {{build_id}} --project=PROJECT_ID

# Show Cloud Run logs
cloud-run-logs:
    @echo "☁️  Fetching logs for Cloud Run environment..."
    gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=CLOUD_RUN_ENDPOINT" --project=PROJECT_ID --limit=100 --format="value(timestamp, severity, textPayload)"

# Shows git logs in timestamped way
git-logs-timestamped:
    git log --pretty=format:'%h %ad | %s%d [%an]' --date=iso -n 10

Note: If just is not available, use a Makefile instead (convert N spaces to tabs).

Adding Environment Variables

This is a complex process. Follow carefully:

1. Add variable to the script (usually in bin/ with "cloud build" in name)
   • Example: bin/ricc-cb-push-to-cloudrun-magic.sh
2. Ensure the variable is passed from Cloud Build in the step that calls it
3. Update the Cloud Run trigger for this service
   • Should be documented in README.md (if not, document it!)
4. Check gcp/ or iac/ folders for additional hints

File Structure

If Cloud Build is set up, expect:

• cloudbuild.yaml (root file, likely has trigger attached)
• Possibly bin/ scripts for deployment
• Possibly gcp/ or iac/ folders with infrastructure code

Resources

• Scripts: Check .gemini/skills/cloud-build-investigation/scripts/ for helper utilities
• References: See .gemini/skills/cloud-build-investigation/references/ for GCP docs

Important Reminders

🚫 DO NOT:

• Change cloudbuild.yaml location or major structure
• Modify build target in justfile without understanding full context
• Make sweeping changes to folder structures
• Auto-stream logs indefinitely (use --stream cautiously)

✅ DO:

• Take baby steps
• Test incrementally
• Document findings in GitHub issues
• Collaborate with the user (Riccardo)
• Cross-correlate timestamps between git and Cloud Build
• Use VERSION file for additional context