CI/CD: Pipelines, Ambientes
y Estrategia de Deploy

Modelo de Branches

Flujo de tres niveles. Las ramas de historia/bug se crean desde release/3.1.0 y vuelven a ella via MR. La rama main solo recibe merges de release.

flowchart TD
    S["story/sN.M/slug\nbug/RAISE-N/slug"]
    R["release/3.1.0\ndesarrollo activo · MR target"]
    M["main\nestable · solo merges de release"]

    S -->|"MR → merge"| R
    R -->|"merge en release"| M
    M -.->|"hotfix"| R

Perfiles de CI

Dos modos de operación según el contexto: un fast path para MRs (~3–5 min) y una suite completa para pre-release. Los jobs de seguridad están temporalmente deshabilitados.

Markers de pytest y cobertura

Estrategia de Cache

Dev — Fly.io (raise-server.fly.dev)

Primer ambiente de integración real. Se despliega al crear un tag dev. Corre smoke + E2E deployed antes de poder promover a producción.

git tag v3.1.0-dev.20260821
git push origin v3.1.0-dev.20260821

Configuración Fly.io (fly.staging.toml)

app = 'raise-server'
primary_region = 'lax'

[deploy]
  release_command = "sh -c 'cd /app/packages/raise-server && alembic upgrade head'"
  # Migración en máquina efímera ANTES del corte (ADR-093)
  # Sin esto → drift schema↔código (patrón de error RAISE-11462)

[env]
  RAI_ENV     = 'staging'
  RAI_LOG_LEVEL = 'INFO'
  RAI_PORT    = '8080'
  # RAI_DATABASE_URL — Fly secret (fly postgres attach)

[http_service]
  internal_port = 8080
  force_https   = true
  auto_stop_machines = 'off'   # nunca hibernar en staging
  min_machines_running = 1

  [[http_service.checks]]
    interval     = '15s'
    timeout      = '5s'
    grace_period = '45s'       # buffer para alembic en cold start
    method       = 'GET'
    path         = '/health'

[[vm]]
  size   = 'shared-cpu-1x'
  memory = '512mb'

Smoke Check en Deploy

QA — GCP Cloud Run

Ambiente de validación en Google Cloud Platform. Ya está parcialmente operativo — es la base del plan de migración. Trigger: push a la branch dedicada ambiente-qa-gcp.

git push origin ambiente-qa-gcp

Flujo de Build — Kaniko

# Autenticación en Artifact Registry (sin Docker daemon)
echo '{"auths":{"northamerica-south1-docker.pkg.dev": {"auth":"..."}}}' \
  > /kaniko/.docker/config.json

# Build multi-stage (target=server) + push con dos tags
/kaniko/executor \
  --context "${CI_PROJECT_DIR}" \
  --dockerfile "${CI_PROJECT_DIR}/Dockerfile" \
  --target server \
  --build-arg "GIT_SHA=${CI_COMMIT_SHA}" \
  --build-arg "BUILD_DATE=$(date -u +%F)" \
  --destination "northamerica-south1-docker.pkg.dev/vaultwarden-server-485620/raise-docker-qa/raise-server:${CI_COMMIT_SHORT_SHA}" \
  --destination "northamerica-south1-docker.pkg.dev/vaultwarden-server-485620/raise-docker-qa/raise-server:latest" \
  --cache=true \
  --skip-unused-stages

Migración de Base de Datos (Cloud Run Job)

# Autenticar con service account
echo "$GCP_SA_KEY_QA" | gcloud auth activate-service-account --key-file=-
gcloud config set project vaultwarden-server-485620

# Actualizar imagen del migration job
gcloud run jobs update raise-migrate-qa \
  --image "$GCP_REGISTRY/raise-server:$CI_COMMIT_SHORT_SHA" \
  --command "sh,-c,cd /app/packages/raise-server && alembic upgrade head" \
  --region northamerica-south1 --quiet

# Ejecutar y esperar a que termine
gcloud run jobs execute raise-migrate-qa \
  --region northamerica-south1 --wait --quiet

Deploy a Cloud Run

gcloud run deploy raise-server-qa \
  --image "$GCP_REGISTRY/raise-server:$CI_COMMIT_SHORT_SHA" \
  --region northamerica-south1 \
  --platform managed \
  --quiet

Producción — Fly.io (raise-server-prod.fly.dev)

Ambiente de producción. Solo se despliega con tags de release (RC o final) y requiere aprobación manual en GitLab antes de ejecutar el deploy.

# Release Candidate
git tag v3.1.0-rc.1

# Release Final
git tag v3.1.0

Configuración Fly.io (fly.production.toml)

app = 'raise-server-prod'
primary_region = 'lax'

[deploy]
  release_command = "sh -c 'cd /app/packages/raise-server && alembic upgrade head'"
  strategy = 'bluegreen'   # ⚠ SOBREESCRITO por --strategy rolling en CI

[env]
  RAI_ENV             = 'production'
  RAI_LOG_LEVEL       = 'WARNING'
  RAI_PORT            = '8080'
  RAI_FEATURE_CARTRIDGES = 'off'   # kill-switch de feature flags (ADR-093)
  # RAI_DATABASE_URL  → Fly secret

[http_service]
  internal_port = 8080
  force_https   = true
  auto_stop_machines = 'off'
  min_machines_running = 1

  [[http_service.checks]]
    interval     = '15s'
    timeout      = '5s'
    grace_period = '45s'
    method       = 'GET'
    path         = '/health'

[[vm]]
  size   = 'shared-cpu-1x'
  memory = '2048mb'          # 4× más que staging

Admin — Cloudflare Pages

El frontend raise-admin (SPA Vite/React) se despliega a Cloudflare Pages. Existen tres variantes: dev automático, QA (GCP) y producción manual.

Diagramas de Deploy

Secuencia completa de jobs según el trigger. Cada flujo es independiente — los triggers no se solapan.

Flujo 1 — MR Fast Path

Corre en todo MR hacia release/*. Sólo test stage — sin build ni deploy.

flowchart LR
    trigger["MR → release/*"]
    trigger --> t1["test:raise-cli-fast\n×3 shards paralelos"]
    trigger --> t2["test:raise-core"]
    trigger --> t3["test:raise-server-fast"]
    trigger --> t4["test:raise-cli-no-xdist"]
    trigger --> t5["check-migrations"]
    trigger --> t6["test:docs-guards"]
    t1 & t2 & t3 & t4 & t5 & t6 --> done["MR verde\n~3–5 min"]

Flujo 2 — Push a release/3.1.0

Corre la suite full + si hay cambios en archivos relevantes, despliega a Dev (Fly.io).

flowchart TD
    push["push → release/3.1.0"]
    push --> full["test:raise-cli-full\ntest:raise-server-full\ntest:raise-cli-recall-gate"]
    push --> guard["check-migrations\nbundle-guard:customui"]
    push --> admin["build:admin → deploy:admin-dev\n(si cambia packages/raise-admin)"]
    push --> docs["docs-deploy\n(si cambian ADRs / portal)"]

Flujo 3 — Tag Dev → Fly.io

Tag v*.*.*-dev.YYYYMMDD. El primer ambiente con deploy real. E2E al final bloquea la promoción.

flowchart LR
    tag["git tag\nv3.1.0-dev.YYYYMMDD"]
    tag --> A["test:raise-server-full"]
    tag --> B["guard:tag-ancestry"]
    tag --> C["build:onnx-model\nallow_failure: true"]
    A & B & C --> D["deploy:dev\nfly.staging.toml\napp: raise-server\nstrategy: rolling\nrunner: jinkoniwashi"]
    D --> E["smoke:dev\n/health · /api/v2/projects\nalembic drift · 90s"]
    E --> F["e2e:dev\ndeployed tests"]

Flujo 4 — Tag RC/Release → Producción Fly.io

Tag de release. El deploy requiere aprobación manual en GitLab. No hay E2E post-production.

flowchart LR
    tag["git tag v3.1.0-rc.N\no v3.1.0"]
    tag --> A["test:raise-server-full"]
    tag --> B["guard:tag-ancestry"]
    tag --> C["build:onnx-model\nallow_failure: true"]
    A & B & C --> GATE["MANUAL\naprobación en GitLab"]
    GATE --> D["deploy:production\nfly.production.toml\napp: raise-server-prod\nstrategy: rolling\nrunner: docker"]
    D --> E["smoke:production\n/health · 90s"]

Flujo 5 — Branch GCP QA

Push a ambiente-qa-gcp. Build con Kaniko, migración manual, deploy a Cloud Run.

flowchart LR
    push["push → ambiente-qa-gcp"]
    push --> O["build:onnx-model\nallow_failure: true"]
    push --> AB["build:admin-qa\nCloudflare Pages QA"]
    O --> K["build:gcp-qa\nKaniko → Artifact Registry\nnortamerica-south1"]
    K --> M["migrate:gcp-qa\nMANUAL\nCloud Run Job"]
    K --> D["deploy:gcp-qa\ngcloud run deploy\nraise-server-qa"]
    D --> S["smoke:gcp-qa\n/health · 120s"]
    AB --> DAD["deploy:admin-qa\nCloudflare Pages"]

Dockerfile y Stack de Servicios

Un único Dockerfile multi-target para todo el monorepo. Estrategia de capas ordenada por frecuencia de cambio para optimizar la cache de Kaniko.

Targets del Dockerfile

Estrategia de Capas (Layer Cache)

Apps Fly.io en el ecosistema

Patrón de Migración DB (crítico para GCP)

El patrón de Fly.io ejecuta Alembic antes del corte de tráfico en una máquina efímera. En GCP QA esto se hace manualmente con un Cloud Run Job. Para producción en GCP, el Job debe ejecutarse y esperar éxito antes del gcloud run deploy.

release_command = "sh -c 'cd \
/app/packages/raise-server \
&& alembic upgrade head'"
# ↑ Corre en máquina efímera.
# Si falla → deploy cancelado.
# Tráfico nunca se corta.

gcloud run jobs execute \
  raise-migrate-prod \
  --region northamerica-south1 \
  --wait --quiet         # ← bloqueante
# Si exit != 0 → abortar.
# Solo después:
gcloud run deploy raise-server-prod \
  ...

Secrets y Variables

Variables configuradas en GitLab Settings → CI/CD → Variables. Las marcadas como Protected solo están disponibles en branches/tags protegidos.

Deuda Técnica — Jobs Deshabilitados

Seis jobs de seguridad fueron comentados en .gitlab-ci.yml durante la fase de desarrollo activo de v3 para mantener ciclos de iteración cortos. La migración a GCP es una oportunidad para reactivarlos.

Referencia para Migración a GCP

Lo que ya existe en GCP, lo que hace falta replicar, y los patrones críticos a respetar durante la transición.

Estado actual por componente

Patrones críticos a respetar

Variables de entorno a configurar en Cloud Run

Health check en Cloud Run

gcloud run deploy raise-server-prod \
  --image "$GCP_REGISTRY/raise-server:$CI_COMMIT_SHORT_SHA" \
  --region northamerica-south1 \
  --platform managed \
  --port 8080 \
  --set-env-vars "RAI_ENV=production,RAI_LOG_LEVEL=WARNING" \
  --set-secrets "RAI_DATABASE_URL=raise-db-url-prod:latest" \
  # Cloud Run health check — equivale al [[http_service.checks]] de Fly.io
  # Se configura en el servicio, no en el deploy command:
  #   Startup probe: GET /health, initial delay 45s (equivale a grace_period)
  #   Liveness probe: GET /health, interval 15s, timeout 5s, failures 3
  --quiet