gcp-cloud-run

---
name: gcp-cloud-run
description: "GCP Cloud Run deployment skill. Use for Cloud Run Functions (event-driven Pub/Sub, Storage, HTTP webhooks), cold start optimization, and Cloud Run anti-pattern prevention. For Cloud Run service deployment use deployment-engineer agent. Triggers: cloud run, cloud function, pub/sub trigger, cold start, serverless, event-driven GCP, cloud storage trigger."
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
metadata:
  triggers: ["cloud run", "cloud function", "pub/sub trigger", "cold start", "serverless", "event-driven GCP", "cloud storage trigger"]
  related-skills: [docker, adk-deploy-guide, architecture-design]
  domain: backend
  role: specialist
  scope: deployment
  output-format: code
last-reviewed: "2026-03-14"
---

# 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

| Task | Use This Skill | Use `deployment-engineer` Agent |
|------|---------------|---------------------------------|
| Pub/Sub consumer function | YES | No |
| Cloud Storage trigger function | YES | No |
| HTTP webhook / short-lived invocation | YES | No |
| Cold start optimization | YES | No |
| Long-running Cloud Run **service** | No | YES |
| CI/CD pipeline design (service) | No | YES |
| Terraform Cloud Run service module | No | YES (`terraform-specialist`) |

**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

| File | Load When |
|------|-----------|
| `reference/cloud-run-functions.md` | Writing a Pub/Sub, Storage, or HTTP trigger function |
| `reference/cold-start-optimization.md` | Function is slow to start or you need `--cpu-boost` flags |
| `assets/cloud-run-antipatterns.md` | Reviewing any Cloud Run code or config for correctness |

---

## 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)

```yaml
# .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`.

• SKILL.md 5 KB
• assets/cloud-run-antipatterns.md 4 KB
• reference/cloud-run-functions.md 9 KB
• reference/cold-start-optimization.md 4 KB