GCP Cloud Run

Iron Law

NO CLOUD RUN FUNCTION WITHOUT:
1. A stack-specific health check endpoint (GET /health → 200)
2. GitHub Actions workflow (NEVER cloudbuild.yaml)
3. Workload Identity Federation (NEVER service account JSON keys)

This Skill vs deployment-engineer Agent

Key distinction: Cloud Run Functions = event-driven, ephemeral, short-lived invocations. Cloud Run Services = long-running, persistent, serve steady traffic → use deployment-engineer.

Pattern Selector

What are you building?
    |
    +-- Pub/Sub consumer, Storage trigger, HTTP webhook?
    |   -> Load: reference/cloud-run-functions.md
    |   -> Pick your stack section (Python, NestJS, Spring Boot, TypeScript/Fastify)
    |
    +-- Cold start is too slow in staging or prod?
    |   -> Load: reference/cold-start-optimization.md
    |   -> Apply flags from the optimization table
    |
    +-- Reviewing existing Cloud Run code or config?
        -> Load: assets/cloud-run-antipatterns.md
        -> Run through checklist before declaring done

Quick Start Checklist

Before writing any Cloud Run Function code:

• Chose event trigger type: Pub/Sub push | Cloud Storage notification | HTTP
• Selected target stack: Python FastAPI | NestJS | Spring Boot WebFlux | TypeScript/Fastify
• Verified runtime version: python:3.14-slim | node:24-alpine | eclipse-temurin:21-jre-alpine
• Confirmed port binding: PORT env var (Cloud Run injects this, default 8080)
• Health check endpoint planned: GET /health → { "status": "ok" }
• WIF configured or planned (no service account JSON keys)
• docker skill loaded for Dockerfile (multi-stage, non-root user)

Reference Files

Cross-References

• Dockerfiles: Load docker skill → reference/dockerfiles.md for all 4 stack Dockerfiles
• Cloud Run Service (long-running): Dispatch deployment-engineer agent
• Terraform infrastructure: Dispatch terraform-specialist agent
• ADK agent on Cloud Run: Use adk-deploy-guide skill (has ADK-specific Cloud Run patterns)
• GitHub Actions pipeline: docs/workflows/deployment-ci-cd.md
• Security review (WIF, secrets): Dispatch security-reviewer agent after implementation

GitHub Actions Deploy Snippet (All Stacks)

# .github/workflows/deploy-function.yml
name: Deploy Cloud Run Function

on:
  push:
    branches: [develop, main]

env:
  PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
  REGION: us-central1
  FUNCTION_NAME: my-function
  REGISTRY: ${{ vars.GCP_REGION }}-docker.pkg.dev

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write    # Required for Workload Identity Federation
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Authenticate to GCP
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ vars.WIF_PROVIDER }}
          service_account: ${{ vars.WIF_SERVICE_ACCOUNT }}

      - name: Build and push image
        run: |
          docker build -t $REGISTRY/$PROJECT_ID/$FUNCTION_NAME:${{ github.sha }} .
          gcloud auth configure-docker $REGISTRY --quiet
          docker push $REGISTRY/$PROJECT_ID/$FUNCTION_NAME:${{ github.sha }}

      - name: Deploy to Cloud Run
        run: |
          gcloud run deploy $FUNCTION_NAME \
            --image $REGISTRY/$PROJECT_ID/$FUNCTION_NAME:${{ github.sha }} \
            --region $REGION \
            --platform managed \
            --no-allow-unauthenticated \
            --cpu-boost \
            --min-instances 0 \
            --max-instances 10

For cold start flags (--cpu-boost, --min-instances, memory/CPU ratio), see reference/cold-start-optimization.md.