gcp-deployment · jleechanorg - Agent Skill

GCP Deployment & Server Management

Purpose: Guide for finding GCP Cloud Run services and deploying Your Project

⚠️ IMPORTANT: This skill is ONLY for the Your Project repository and GCP project. The deployment scripts, service names, and configurations are specific to this project and will not work for other repositories or GCP projects.

Project Overview

Repository: https://github.com/jleechanorg/your-project.com Project: Your Project GCP Project ID: worldarchitecture-ai (specific to this project only) Region: us-central1 Platform: Google Cloud Run (containerized deployments)

Scope: All commands, scripts, and service references in this document are specific to the worldarchitecture-ai GCP project and will not work with other GCP projects or repositories.

? Quick Reference

Service URLs

Environment	Service Name	URL
Production	mvp-site-app-stable	https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app
Staging	mvp-site-app-staging	https://mvp-site-app-staging-i6xf2p72ka-uc.a.run.app
Development	mvp-site-app-dev	https://mvp-site-app-dev-i6xf2p72ka-uc.a.run.app
PR Preview	mvp-site-app-s1 through s10	Rotating pool (see PR Preview section below)

Health Check Endpoints

Add /health to any service URL:

? Finding GCP Services

Method 1: Cloud Console (Web UI)

Navigate to Cloud Run:

https://console.cloud.google.com/run?project=worldarchitecture-ai

Filter by service name: Look for mvp-site-app* services
View service details: Click on any service to see:
- Service URL
- Revisions
- Configuration
- Logs
- Metrics

Method 2: gcloud CLI

# List all Cloud Run services
gcloud run services list \
  --project=worldarchitecture-ai \
  --region=us-central1

# Get specific service details
gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --format=yaml

# Get service URL
gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --format="value(status.url)"

Method 3: From Repository

The deployment script automatically determines the correct service:

# Check what will be deployed
cat scripts/deploy_common.sh | grep -A 10 "SERVICE_NAME="

Service naming pattern:

Dev: mvp-site-app-dev
Staging: mvp-site-app-staging
Production: mvp-site-app-stable

? Deployment Methods

Deployment Decision Tree

Need to deploy?
├─ Production/Stable? → Use GitHub Actions (Required)
├─ Staging? → Use ./deploy.sh staging (local deployment)
└─ Development? → Use ./deploy.sh (local) OR auto-deploys on push to main

Method 1: Local Deployment (Dev/Staging Only)

Development (Default):

./deploy.sh
# OR explicitly
./deploy.sh mvp_site

Staging:

./deploy.sh mvp_site staging

Production (BLOCKED locally):

./deploy.sh mvp_site stable
# ❌ This will fail with safety message directing you to GitHub Actions

Auto-detection: The script automatically detects deployable apps if run from project root:

# If current directory has Dockerfile, uses current directory
# Otherwise shows interactive menu of available apps
./deploy.sh

Method 2: GitHub Actions (Production & Development)

Production/Stable Deployment (Required Method)

Via CLI:

# Trigger production deployment
gh workflow run deploy-production.yml \
  -f confirm_production="DEPLOY TO PRODUCTION"

# Check deployment status
gh run list --workflow=deploy-production.yml --limit 1
gh run view <run-id>

Via GitHub Web UI:

Go to: https://github.com/jleechanorg/your-project.com/actions/workflows/deploy-production.yml
Click "Run workflow"
Type "DEPLOY TO PRODUCTION" in confirmation field
Click "Run workflow"
Wait for approval (protected environment)
Deployment proceeds after approval

Why GitHub Actions Required for Production:

✅ Proper approval process
✅ Full audit trail
✅ Prevents accidental deployments
✅ Team visibility
✅ Protected environment with manual approval gate

Auto-Deploy on Push to Main (Development)

Development environment auto-deploys when code is pushed to main branch:

Workflow: .github/workflows/auto-deploy-dev.yml

Trigger:

git push origin main
# Automatically triggers deployment to dev environment

Check auto-deploy status:

gh run list --workflow=auto-deploy-dev.yml --limit 3

? Deployment Script Details

Main Script: `./deploy.sh`

Location: Project root Purpose: Context-aware deployment with auto-detection

Usage:

./deploy.sh [TARGET_DIR] [ENVIRONMENT]

Examples:

# Deploy from current directory to dev (if Dockerfile exists)
./deploy.sh

# Deploy specific app to dev
./deploy.sh mvp_site

# Deploy to staging
./deploy.sh mvp_site staging

# Attempt production (will be blocked)
./deploy.sh mvp_site stable

Environment Mapping:

dev (default): Development environment
staging: Staging environment
stable, prod, production: Production (GitHub Actions only)

Helper Script: `scripts/deploy_common.sh`

Purpose: Shared deployment logic Contains:

Service name mapping
GCP configuration
Cloud Build submission
Autoscaling settings

Service Name Logic:

if [[ "$ENVIRONMENT" == "stable" ]]; then
    SERVICE_NAME="mvp-site-app-stable"
elif [[ "$ENVIRONMENT" == "staging" ]]; then
    SERVICE_NAME="mvp-site-app-staging"
else
    SERVICE_NAME="mvp-site-app-dev"
fi

? Configuration Details

Autoscaling

Current Settings (all environments):

Max Instances: 6
Min Instances: 0 (scales to zero when not in use)

Why 6 instances:

Sanity-check threshold to prevent runaway costs
Adequate for current traffic patterns
Can be adjusted in deploy.sh (MAX_INSTANCES variable)

Environment Variables

Set via GCP Console:

Navigate to service in Cloud Run
Click "Edit & Deploy New Revision"
Go to "Variables & Secrets" tab
Add/modify environment variables

Common variables:

GEMINI_API_KEY: Google Gemini API key
FIREBASE_CREDENTIALS: Firebase service account JSON
Environment-specific configs

Cloud Build

Build timeout: 10 minutes (configurable) Build logs: Streamed to terminal during deployment Build configuration: Defined in Dockerfile in target directory

? Monitoring & Logs

View Logs

Via Console:

# Production logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-stable%22

# Staging logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-staging%22

# Dev logs
https://console.cloud.google.com/logs/query?project=worldarchitecture-ai&query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22mvp-site-app-dev%22

Via gcloud CLI:

# Stream production logs
gcloud run services logs read mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --limit=50

# Follow logs in real-time
gcloud run services logs tail mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1

Check Service Health

# Production health check
curl https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app/health

# Staging health check
curl https://mvp-site-app-staging-i6xf2p72ka-uc.a.run.app/health

# Dev health check
curl https://mvp-site-app-i6xf2p72ka-uc.a.run.app/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2025-11-14T18:35:44Z"
}

?️ Safety Features

Production Deployment Protection

Local deployment blocked:

./deploy.sh mvp_site stable
# Output:
# ? PRODUCTION DEPLOYMENT BLOCKED ?
# Production deployments are NOT allowed from local machines for safety.

GitHub Actions protection:

Protected environment: production
Manual approval required
Input validation: Must type "DEPLOY TO PRODUCTION"
Full audit trail in GitHub Actions

Deployment Validation

Pre-deployment checks:

Dockerfile exists in target directory
Valid environment specified
GCP authentication configured (GitHub Actions)
Service name correctly mapped

Post-deployment checks:

Service deployed successfully
Health endpoint returns 200 OK
Revision created and serving traffic

? Authentication

Local Development

GCP Authentication:

# Login to GCP
gcloud auth login

# Set project
gcloud config set project worldarchitecture-ai

# Verify authentication
gcloud auth list

GitHub Actions

Authentication: Workload Identity Federation Service Account: github-actions@worldarchitecture-ai.iam.gserviceaccount.com Configured in: .github/workflows/*.yml

Secrets required:

GCP_WORKLOAD_IDENTITY_PROVIDER: Workload identity provider
GCP_SERVICE_ACCOUNT: Service account email

? Common Tasks

Deploy to Production

# 1. Trigger deployment
gh workflow run deploy-production.yml \
  -f confirm_production="DEPLOY TO PRODUCTION"

# 2. Monitor deployment
gh run list --workflow=deploy-production.yml --limit 1

# 3. View detailed logs
gh run view <run-id>

# 4. Verify health
curl https://mvp-site-app-stable-i6xf2p72ka-uc.a.run.app/health

Deploy to Staging

# Local deployment (staging uses local deployment only)
./deploy.sh mvp_site staging

Deploy to Development

# Option 1: Local deployment
./deploy.sh mvp_site

# Option 2: Push to main (auto-deploys)
git push origin main

# Option 3: Manual GitHub Actions trigger
gh workflow run auto-deploy-dev.yml

Check Current Deployment

# List all services
gcloud run services list \
  --project=worldarchitecture-ai \
  --region=us-central1

# Get specific service status
gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1

# Check recent deployments
gh run list --workflow=deploy-production.yml --limit 5

Rollback Deployment

# List revisions
gcloud run revisions list \
  --service=mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1

# Route traffic to previous revision
gcloud run services update-traffic mvp-site-app-stable \
  --to-revisions=<REVISION-NAME>=100 \
  --project=worldarchitecture-ai \
  --region=us-central1

? Troubleshooting

Deployment Fails

Check build logs:

# View recent Cloud Build logs
gcloud builds list \
  --project=worldarchitecture-ai \
  --limit=5

# Get specific build details
gcloud builds describe <BUILD-ID> \
  --project=worldarchitecture-ai

Service Not Responding

Check service status:

gcloud run services describe mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --format=yaml

Check logs:

gcloud run services logs read mvp-site-app-stable \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --limit=100

Authentication Issues

Local:

# Re-authenticate
gcloud auth login
gcloud auth application-default login

# Verify project
gcloud config get-value project

GitHub Actions:

Check Workload Identity Federation configuration
Verify service account permissions
Review workflow run logs for auth errors

? Additional Resources

Documentation Links

Cloud Run Console: https://console.cloud.google.com/run?project=worldarchitecture-ai
Cloud Build Console: https://console.cloud.google.com/cloud-build?project=worldarchitecture-ai
GitHub Actions: https://github.com/jleechanorg/your-project.com/actions
GCP Logs: https://console.cloud.google.com/logs?project=worldarchitecture-ai

Related Files

Main deployment script: ./deploy.sh
Common deployment logic: scripts/deploy_common.sh
Production workflow: .github/workflows/deploy-production.yml
Auto-deploy workflow: .github/workflows/auto-deploy-dev.yml

Contact & Support

Repository: https://github.com/jleechanorg/your-project.com
Issues: https://github.com/jleechanorg/your-project.com/issues

? Best Practices

Always test in dev/staging first before production
Use health checks to verify deployments
Monitor logs during and after deployment
Keep autoscaling limits reasonable to control costs
Use GitHub Actions for production deployments
Tag releases when deploying to production
Document environment variables in team docs
Review Cloud Run metrics regularly

? PR Preview Deployments

Overview

PR preview deployments are automatically created for pull requests via the "Deploy PR Preview (Rotating Pool)" workflow. These deployments use a rotating pool of services (mvp-site-app-s1 through mvp-site-app-s10) to provide isolated preview environments for testing PR changes.

Finding PR Preview URLs

Method 1: From GitHub Actions (Recommended)

Get URL from latest PR preview deployment:

# Get the latest PR preview deployment run
RUN_ID=$(gh run list --workflow="Deploy PR Preview (Rotating Pool)" --limit=1 --json databaseId -q '.[0].databaseId')

# Extract deployment URL from logs
gh run view --log "$RUN_ID" | grep "PREVIEW_URL:" | grep -oE "https://[^[:space:]]+\.run\.app"

Get URL for specific PR:

# Find deployment run for PR #3490
gh run list --workflow="Deploy PR Preview (Rotating Pool)" --limit=50 --json databaseId,displayTitle | \
  python3 -c "import sys, json; runs = json.load(sys.stdin); \
  matches = [r for r in runs if '3490' in r.get('displayTitle', '')]; \
  print(matches[0]['databaseId'] if matches else 'No matching runs found')"

# Then get URL from that run's logs
gh run view --log <RUN_ID> | grep "PREVIEW_URL:"

Note: If no matching runs are found, increase the --limit value or verify the PR number. The defensive Python snippet above will print "No matching runs found" instead of raising an IndexError.

Method 2: From gcloud (Current Service)

List all PR preview services:

gcloud run services list \
  --project=worldarchitecture-ai \
  --region=us-central1 \
  --filter="name:mvp-site-app-s*" \
  --format="table(name,status.url,metadata.labels.`pr-number`)"