Skip to content
Engineering

CI/CD Pipelines & Cloud Build

1. Monorepo Pipeline Architecture

Section titled “1. Monorepo Pipeline Architecture”

The GERCIA platform leverages Google Cloud Build (Region: southamerica-east1 - São Paulo) as its enterprise continuous integration and continuous delivery (CI/CD) engine. The monorepo operates six specialized, high-performance pipelines under deploy/, ensuring deterministic compilation, immutable artifact promotion, and zero-trust deployment across our infrastructure:

flowchart TD
    subgraph TRIGGERS ["Git Triggers (Push to staging / main)"]
        T_DOTNET["dotnet/**<br>deploy/cloudbuild.dotnet.yaml"]
        T_APP["apps/app/**<br>deploy/cloudbuild.app.yaml"]
        T_SITE["apps/site/**<br>deploy/cloudbuild.site.yaml"]
        T_VET["apps/site-vet/**<br>deploy/cloudbuild.site-vet.yaml"]
        T_DOCS["docs/**<br>deploy/cloudbuild.docs.yaml"]
        T_STATUS["apps/status/**<br>deploy/cloudbuild.status.yaml"]
    end

    subgraph PIPELINES ["Google Cloud Build Pipelines (southamerica-east1)"]
        P_DOTNET["1. cloudbuild.dotnet.yaml<br>(.NET 10 Server Host & Tests)"]
        P_APP["2. cloudbuild.app.yaml<br>(Enterprise Angular 22 SPA)"]
        P_SITE["3. cloudbuild.site.yaml<br>(Institutional Public Site)"]
        P_VET["4. cloudbuild.site-vet.yaml<br>(Veterinary Public Site)"]
        P_DOCS["5. cloudbuild.docs.yaml<br>(Private & Public Starlight Docs)"]
        P_STATUS["6. cloudbuild.status.yaml<br>(Out-of-Band Status Page)"]
    end

    subgraph DESTINATIONS ["Deployment Targets"]
        D_RUN["Google Cloud Run (Serverless)<br>(Gercia.Server & gercia-migrator Job)"]
        D_GAR["Google Artifact Registry<br>(Standardized Container Images)"]
        D_CF_APP["Cloudflare Pages<br>(gercia-app / app.*, ops.*, vet.*)"]
        D_CF_SITE["Cloudflare Pages<br>(gercia / gercia.com.br)"]
        D_CF_VET["Cloudflare Pages<br>(gercia-site-vet / gercia.vet.br)"]
        D_CF_ENG["Cloudflare Pages<br>(gercia-docs-private / eng.gercia.com.br)"]
        D_CF_DOCS["Cloudflare Pages<br>(gercia-docs-public / docs.gercia.com.br)"]
        D_CF_STATUS["Cloudflare Pages<br>(gercia-status / status.gercia.com.br)"]
    end

    T_DOTNET --> P_DOTNET
    T_APP --> P_APP
    T_SITE --> P_SITE
    T_VET --> P_VET
    T_DOCS --> P_DOCS
    T_STATUS --> P_STATUS

    P_DOTNET --> D_GAR --> D_RUN
    P_APP --> D_CF_APP
    P_SITE --> D_CF_SITE
    P_VET --> D_CF_VET
    P_DOCS --> D_CF_ENG & D_CF_DOCS
    P_STATUS --> D_CF_STATUS

2. Platform Backend Engine Pipeline (cloudbuild.dotnet.yaml)

Section titled “2. Platform Backend Engine Pipeline (cloudbuild.dotnet.yaml)”

The primary platform pipeline compiles, tests, containerizes, and deploys the unified .NET 10 backend host (Gercia.Server) and triggers ephemeral schema migrations via Cloud Run Jobs (gercia-migrator). It executes on Google Cloud’s E2_HIGHCPU_8 machine type (8 vCPUs, 8 GB RAM) to maximize build throughput.

Pipeline Execution Graph (DAG)

Section titled “Pipeline Execution Graph (DAG)”

To minimize CI/CD execution time, the pipeline uses Cloud Build’s native waitFor: directives, executing Docker builds and cache operations concurrently:

flowchart TD
    CACHE["1. Restore NuGet Cache (gsutil)"] --> TESTS["2. Run Unit & Architecture Tests<br>(Gercia.UnitTests.slnf)"]

    subgraph PIPELINE ["Unified Build & Cache (8 vCPUs)"]
        TESTS --> B_SERVER["3. Build or Promote Image: gercia-server"]
        TESTS --> S_CACHE["4. Save NuGet Cache to GCS"]
    end

    B_SERVER --> PUSH["5. Push Unified Image (Artifact Registry)"]
    PUSH --> MIGRATE["6. Execute Cloud Run Job: gercia-migrator<br>(--migrate & --seed)"]
    MIGRATE --> DEPLOY["7. Deploy Revision to Google Cloud Run<br>(api-stg / api-prd)"]
    DEPLOY --> NOTIFY["8. Notify Google Chat"]
    S_CACHE --> NOTIFY

Key Architectural Invariants:

Section titled “Key Architectural Invariants:”
  1. Immutable Promotion Pattern (Build Once, Deploy Anywhere):
    • On staging branch: Compiles source code, runs tests, builds the single unified Docker image (gercia-server) using layer caching, and tags the image with $COMMIT_SHA and staging.
    • On main branch (Production): The pipeline never recompiles from source. It pulls the exact binary image validated in staging, retags it with main and $COMMIT_SHA, and promotes it to production Cloud Run services and jobs. This guarantees 100% binary parity between environments.
  2. Standardized Artifact Registry & FinOps Lifecycle:
    • Images are pushed exclusively to the canonical repository $_LOCATION-docker.pkg.dev/$PROJECT_ID/$_REPOSITORY/<service>:<tag>:
      • Repository URI: southamerica-east1-docker.pkg.dev/gercia-gcp/gercia-platform
      • Canonical Image: gercia-server (Unified ASP.NET Core Host: REST API Gateway, OpenIddict STS, AI MCP Protocol, and Migration CLI Runner)
    • Automated FinOps Cleanup Policies: The gercia-platform repository enforces active automated lifecycle policies to prevent disk bloat and control GCP storage costs:
      • delete-untagged-after-14d: Automatically purges untagged (UNTAGGED) container digests older than 14 days (1,209,600s).
      • keep-recent-10-versions: Retains the latest 10 versions for active tags (staging, main, $COMMIT_SHA), guaranteeing immediate rollback capability while eliminating stale layers.
    • Decommissioned Legacy Repositories: The legacy gercia repository (1.51 GB) and obsolete microservice packages (gercia-api, gercia-web, gercia-worker, gercia-mcp, gercia-logshipper, gercia-notify) were permanently retired.
  3. Automated Serverless Rollout (Google Cloud Run):
    • Staging: Automatic continuous deployment to Cloud Run revisions with 100% traffic assignment upon build completion.
    • Production: Deploys zero-downtime rolling revisions with automated HTTP health checks (--health).
  4. Solution Filters & Workload Segregation (Gercia.Server.slnf & Gercia.UnitTests.slnf):
    • The test step validates server compilation using Gercia.Server.slnf and executes unit and architecture tests via Gercia.UnitTests.slnf (see Solution Filters & Workload Segregation), completely eliminating mobile toolchain dependencies in the Cloud Build Linux container.

3. Enterprise Angular SPA Pipeline (cloudbuild.app.yaml)

Section titled “3. Enterprise Angular SPA Pipeline (cloudbuild.app.yaml)”

The enterprise presentation layer (apps/app/, package @gercia/app) serves human healthcare (app.gercia.com.br), veterinary clinics (app.gercia.vet.br), and backoffice operations (ops.gercia.com.br):

  1. Monorepo Directory: apps/app/ (@gercia/app).
  2. Quality Gate (Automated Unit Tests): Executes pnpm --filter @gercia/app test (14 unit tests across PortalService, AuthService, and AppComponent). If any test fails, deployment aborts immediately.
  3. Application Build & Output Structure: Executes pnpm --filter @gercia/app run build, compiling Angular 22 Zoneless Signals into apps/app/dist/app/browser/.
  4. Cloudflare SPA Routing Rule (_redirects): Angular build copies apps/app/public/_redirects (/* /index.html 200) into dist/app/browser/_redirects, ensuring all client-side routes resolve without HTTP 404.
  5. Edge Functions & Wrangler Deployment: Executes npx wrangler pages deploy dist/app/browser targeting Cloudflare Pages project gercia-app (with --branch="$BRANCH_NAME" and --commit-hash="$COMMIT_SHA"). Wrangler compiles and uploads Edge Functions (apps/app/functions/api/ops/me.ts) alongside static browser bundles.

4. Unified Documentation Portals Pipeline (cloudbuild.docs.yaml)

Section titled “4. Unified Documentation Portals Pipeline (cloudbuild.docs.yaml)”

Builds and deploys both documentation portals simultaneously in parallel:

  1. Concurrent Static Builds (Astro Starlight):
    • Private Architecture Portal: Builds docs/private/ with Pagefind indexing and Mermaid diagram transformations.
    • Public Help Center: Builds docs/public/ with multilingual guides for doctors, pharmacies, and patients.
  2. Cloudflare Pages Deployments:
    • Deploys docs/private/dist to project gercia-docs-private (bound to https://eng.gercia.com.br and https://eng-stg.gercia.com.br, secured with Cloudflare Zero Trust).
    • Deploys docs/public/dist to project gercia-docs-public (bound to https://docs.gercia.com.br and https://docs-stg.gercia.com.br).

5. Institutional Public Site Pipeline (cloudbuild.site.yaml)

Section titled “5. Institutional Public Site Pipeline (cloudbuild.site.yaml)”

The institutional marketing site is consolidated under apps/site/ within the root monorepo, managed via pnpm workspaces (@gercia/site):

  1. Monorepo Directory: apps/site/ (@gercia/site).
  2. Static Build: Executes pnpm run build:site, compiling Astro 7, Tailwind CSS v4, and Svelte 5 into apps/site/dist/.
  3. Wrangler Deployment: Deploys dist targeting Cloudflare Pages project gercia (bound to https://gercia.com.br and https://staging.gercia.pages.dev).

6. Sovereign Veterinary Public Site Pipeline (cloudbuild.site-vet.yaml)

Section titled “6. Sovereign Veterinary Public Site Pipeline (cloudbuild.site-vet.yaml)”

The sovereign marketing site for the veterinary healthcare vertical is consolidated under apps/site-vet/ within the root monorepo, managed via pnpm workspaces (@gercia/site-vet):

  1. Monorepo Directory: apps/site-vet/ (@gercia/site-vet).
  2. Static Build: Executes pnpm run build:site-vet, compiling Astro 7, Tailwind CSS v4, and Svelte 5 into apps/site-vet/dist/.
  3. Wrangler Deployment: Deploys dist targeting Cloudflare Pages project gercia-site-vet (bound to https://gercia.vet.br and https://staging.gercia-site-vet.pages.dev).

7. Out-of-Band Status Page Pipeline (cloudbuild.status.yaml)

Section titled “7. Out-of-Band Status Page Pipeline (cloudbuild.status.yaml)”

Builds and deploys the out-of-band status and incident management portal (apps/status/) to Cloudflare Pages:

  1. Static Build: Installs dependencies and builds the Astro 7, Tailwind CSS v4, and Svelte 5 status application (apps/status/).
  2. Wrangler Deployment: Deploys dist targeting project gercia-status (bound to https://status.gercia.com.br and https://status-stg.gercia.com.br).

8. Architectural Decision: Cloud Build Direct Upload vs Cloudflare Pages Native Git

Section titled “8. Architectural Decision: Cloud Build Direct Upload vs Cloudflare Pages Native Git”

The platform strictly enforces Google Cloud Build Push-Based Direct Upload over Cloudflare Pages native Git integration:

Evaluation Dimension Cloudflare Pages Native Git Integration Google Cloud Build + Wrangler Direct Upload (Standard)
Monorepo Build Concurrency ⚠️ 1 concurrent build limit across entire CF account. 5 frontends trigger serial queue stalls (15-20 min). ✅ Elastic multi-worker concurrency. Zero pipeline stalls.
Secret Management ⚠️ Decentralized. Requires manually maintaining tokens and variables in CF Web UI. ✅ Centralized in Google Secret Manager (GSM) (CF_API_TOKEN, CF_ACCOUNT_ID, WEBHOOK_URL).
Automated Test Gates ⚠️ No native test step. Failures only caught if embedded in npm build script. ✅ Strict test gates (ng test, architecture tests) aborting deploys on failure.
Edge Deployment Speed ⚠️ Clones entire monorepo and reinstalls pnpm on every build (3-5 min per project). ✅ 3 to 5 second atomic asset upload via Wrangler CLI to Anycast Edge.

9. Production Google Cloud Build Triggers Specification

Section titled “9. Production Google Cloud Build Triggers Specification”

All CI/CD automation runs in Google Cloud’s southamerica-east1 (São Paulo) region.

Trigger Configuration Matrix

Section titled “Trigger Configuration Matrix”
Specification Platform Backend (gercia-dotnet) Enterprise SPA (gercia-app) Documentation (gercia-docs) Public Site (gercia-site) Veterinary Site (gercia-site-vet) Status Page (gercia-status)
Trigger Name gercia-dotnet gercia-app gercia-docs gercia-site gercia-site-vet gercia-status
GCP Region southamerica-east1 southamerica-east1 southamerica-east1 southamerica-east1 southamerica-east1 southamerica-east1
Repository gercia/gercia-platform gercia/gercia-platform gercia/gercia-platform gercia/gercia-platform gercia/gercia-platform gercia/gercia-platform
Event Type Push to branch Push to branch Push to branch Push to branch Push to branch Push to branch
Branch Regex ^main$|^staging$ ^main$|^staging$ ^main$|^staging$ ^main$|^staging$ ^main$|^staging$ ^main$|^staging$
Config File deploy/cloudbuild.dotnet.yaml deploy/cloudbuild.app.yaml deploy/cloudbuild.docs.yaml deploy/cloudbuild.site.yaml deploy/cloudbuild.site-vet.yaml deploy/cloudbuild.status.yaml
Included Files dotnet/**
deploy/cloudbuild.dotnet.yaml		 apps/app/**
deploy/cloudbuild.app.yaml		 docs/**
deploy/cloudbuild.docs.yaml		 apps/site/**
deploy/cloudbuild.site.yaml		 apps/site-vet/**
deploy/cloudbuild.site-vet.yaml		 apps/status/**
deploy/cloudbuild.status.yaml
Machine Type E2_HIGHCPU_8 Standard Standard Standard Standard Standard
Build Timeout 1800s (30 min) 600s (10 min) 900s (15 min) 600s (10 min) 600s (10 min) 300s (5 min)
Logging Mode CLOUD_LOGGING_ONLY CLOUD_LOGGING_ONLY CLOUD_LOGGING_ONLY CLOUD_LOGGING_ONLY CLOUD_LOGGING_ONLY CLOUD_LOGGING_ONLY
Status Enabled Enabled Enabled Enabled Enabled Enabled