CI/CD Architecture: Multi-Environment Deployment Pipeline

This document describes our production CI/CD architecture for a Turborepo with backend services on Google Cloud Run and frontend apps on Vercel.

Pipeline Overview

Our implementation uses a three-environment approach with GitHub's native Merge Queue:

Environment Strategy

Backend (Cloud Run via Terraform)

preview: Shared backend for PR testing (manual trigger)
staging: Production-like validation (auto on merge)
prod: Production (auto after staging health checks)

Frontend (Vercel)

Preview: Automatic per PR
Production: Automatic on main
Staging: Optional custom environment

Workflow Architecture

Core Workflows

CI Validation: .github/workflows/ci-merge-group.yml
- Runs on merge_group and pull_request
- Fast typecheck/lint/build for Merge Queue gating
- Required check for branch protection
Preview Deployment: .github/workflows/deploy-preview-on-label.yml
- Triggered by deploy-preview label on PR
- Builds and deploys to shared preview backend
- Safe for testing infrastructure changes
Production Pipeline: .github/workflows/deploy-staging-prod-on-main.yml
- Triggered on push to main
- Sequential: build → staging → tag → production
- Same image tag ensures parity between environments

Merge Queue Integration

GitHub's native Merge Queue on main branch
Required check: build-test job from CI workflow
Automatic serialization of merge operations
Prevents broken main branch state

Infrastructure Management

Container Images

Registry: Google Container Registry (eu.gcr.io)
Tagging: sha-<commit>-<timestamp>
Strategy: Build once, promote many (same tag across environments)

Terraform State

Backend: Google Cloud Storage
Isolation: Workspace per environment (preview, staging, prod)
Resources: Environment-suffixed Cloud Run services and IAM

Configuration Management

Environment files: terraform/environments/{preview,staging,prod}.tfvars
Secrets: Google Secret Manager with per-environment service accounts
Variables: Injected via Terraform -var flags from CI

Environment Characteristics

Aspect	Preview	Staging	Production
Trigger	Manual (label)	Auto (merge)	Auto (after staging)
Resources	1 CPU, 1Gi, min=0	2 CPU, 2Gi, min=1	2 CPU, 2Gi, min=1
Purpose	Feature testing	Integration validation	Live traffic
Isolation	Shared backend	Dedicated	Dedicated
Health checks	No	Yes	Yes

Deployment Flow Details

Preview Deployment

Developer adds deploy-preview label to PR
Workflow builds fresh images with PR commit SHA
Terraform deploys to preview workspace
Shared preview backend is updated

Staging → Production Pipeline

PR passes CI checks and merges via Merge Queue
Build job creates images tagged with main commit SHA
Staging job deploys images and runs health checks
Release job creates git tag and deploys to production
Same image tag ensures staging/production parity

Benefits of This Architecture

Build Once, Deploy Many

Same container images from staging to production
Eliminates drift between environments
Faster production deployments (no rebuild)

Environment Isolation

Separate Terraform workspaces and state
Independent scaling and configuration
Safe testing of infrastructure changes

Merge Queue Integration

Automatic serialization prevents conflicts
Fast feedback via CI checks
Reliable main branch state

Cost Optimization

Shared preview backend reduces resource usage
Zero-instance scaling for preview environment
Efficient resource allocation per environment

Frontend Integration

Vercel Deployment Pattern

Preview: Automatic per PR with branch URLs
Production: Automatic on main branch
Backend URLs: Environment-specific via env vars or DNS

Backend URL Strategy

// Environment-specific backend URLs
const API_URLS = {
  preview: 'https://video-processor-preview-xyz.run.app',
  staging: 'https://video-processor-staging-xyz.run.app', 
  production: 'https://video-processor-prod-xyz.run.app'
}

Operational Considerations

Monitoring and Observability

Health check endpoints on all services
Terraform output URLs for each environment
Release tagging for deployment tracking

Rollback Strategy

Re-run production deployment with previous commit
Terraform manages infrastructure state transitions
Container images remain immutable

Security Model

Workload Identity for GCP authentication
Per-environment service accounts with minimal permissions
Secret Manager for sensitive configuration

This architecture provides a robust, scalable foundation for multi-environment deployments while maintaining development velocity and operational safety.