Versión: 1.0
Fecha: 2026-05-11
Estado: PROPUESTO (Fase 1 — diseño)
Autor: Carlos Alberto Torres Camargo (arquitecto)
Documentos relacionados: ADR-003 Política Entrega QA, PIPELINE_CICD, GITFLOW_DETALLADO, DEFINITION_OF_DONE
Extender el pipeline Jenkins compartido centrica-pipeline-shared@v1.0.4 (que hoy soporta 22 repos backend Java + 3 libraries Java) para incorporar el ecosistema Vault, que introduce dos stacks nuevos al flujo CI/CD de Nebula:
nebula-vault con app vault-shell).Este documento NO toca los pipelines existentes Java. Es aditivo.
| Repo | Project ID | Stack | Estado actual del repo | Container hoy |
|---|---|---|---|---|
nebula/vault/legacy/datavault-backend |
45 | Python 3.11 + FastAPI 0.104 + uvicorn + SQLAlchemy 2 + Alembic + asyncpg | Activo, desarrollo continuo en develop (Plan C multitenant_key) |
datavault-backend:latest en nodo-02 |
nebula/vault/legacy/datavault-oais-server |
47 | Python 3.11 OAIS service worker (sin FastAPI) | Activo, desarrollo continuo en develop |
oais-watcher (python:3.11-slim) en nodo-02 |
nebula/vault/nebula-vault |
44 | Nx 21 + Angular 21 + TypeScript + vitest + Playwright | Activo, semana 8 completada en develop |
Sin container desplegado |
| Repo | Motivo |
|---|---|
nebula/vault/legacy/datavault-frontend (id 46) |
Frontend Angular legacy. Reemplazado por nebula-vault. Se retira cuando nebula-vault esté en producción. |
nebula/vault/vault (id 48) — librería @nebula/vault@0.1.0 |
Scaffold inicial (1 commit). Se integra en fase posterior cuando el equipo lo pueble. |
legacy/ sin mover/renombrar. El grupo legacy/ es nombre histórico, no implica deprecado.datavault-backend (Python) y nebula-vault (Angular).centrica-pipeline-sharedLa library centrica-pipeline-shared (hoy v1.0.4) bumpeará a v1.1.0 cuando se libere esta integración. Mientras tanto se desarrolla en branch feature/pipeline-vault.
pythonServicePipeline() (nuevo)Para repos Python 3.11 con FastAPI o service workers. Caso aplicable: datavault-backend, datavault-oais-server.
Parámetros:
pythonServicePipeline(
serviceName : 'datavault-backend', // requerido
imagePath : 'datavault/datavault-backend', // requerido (registry path)
composeDir : 'datavault', // requerido (carpeta del compose en nodo)
pythonVersion : '3.11', // default 3.11
requirements : 'requirements.txt', // default
testCmd : 'pytest --cov=app --cov-report=xml', // default
lintCmd : 'ruff check . || true', // default (no bloquea inicial; bloquea en v1.1.x)
branchEnvMap : ['develop':'dev','qa':'qa','main':'prod'],
deploy : true // default
)
Stages:
| # | Stage | Acción |
|---|---|---|
| 1 | Checkout | checkout scm |
| 2 | Setup Python | python --version, opcionalmente pyenv para fijar 3.11 |
| 3 | Install deps | pip install --upgrade pip && pip install -r requirements.txt (en venv aislado) |
| 4 | Lint | ruff check . (no bloqueante en v1.1.0; ajusta política luego) |
| 5 | Tests | pytest --cov=app --cov-report=xml (cobertura ≥ 70% como DoD-DEV) |
| 6 | SonarQube | sonar-scanner con sonar.python.coverage.reportPaths=coverage.xml |
| 7 | Docker Build & Push | Igual que microservicePipeline — tags rolling + inmutable |
| 8 | Deploy | Si deploy:true y branch in branchEnvMap, ejecuta docker compose pull && up -d en nodo correspondiente |
Diferencias vs microservicePipeline (Java):
coverage.xml (Cobertura format) en lugar de jacoco.xml.oais-server), el deploy es solo docker compose up -d sin healthcheck HTTP — se confía en docker ps healthy del propio compose.angularNxPipeline() (nuevo)Para Nx workspaces con apps Angular. Caso aplicable: nebula-vault.
Parámetros:
angularNxPipeline(
appName : 'vault-shell', // requerido — nombre de la app Nx
imagePath : 'nebula/vault/nebula-vault', // requerido (registry path)
composeDir : 'nebula/vault', // requerido
nodeVersion : '22', // default 22, lee .nvmrc si existe
pkgManager : 'npm', // npm | pnpm | yarn (default: npm)
e2e : false, // ejecutar Playwright e2e? (default false en dev, true en qa/main)
branchEnvMap: ['develop':'dev','qa':'qa','main':'prod'],
deploy : true
)
Stages:
| # | Stage | Acción |
|---|---|---|
| 1 | Checkout | checkout scm |
| 2 | Setup Node | NodeJS plugin lee .nvmrc (espera 22.x) |
| 3 | Install deps | npm ci (lockfile estricto) |
| 4 | Lint | nx run-many --target=lint --all --skip-nx-cache |
| 5 | Tests unitarios | nx run-many --target=test --all --configuration=ci (vitest) |
| 6 | E2E (condicional) | nx run vault-shell-e2e:e2e --configuration=ci si branch in ['qa','main'] o e2e:true |
| 7 | Build | nx build vault-shell --configuration=<env> (dev |
| 8 | SonarQube | sonar-scanner con sonar.javascript.lcov.reportPaths=coverage/**/*.lcov |
| 9 | Docker Build & Push | Multi-stage: build Angular en node, sirve dist/ con nginx:alpine |
| 10 | Deploy | Si deploy:true y branch in branchEnvMap, deploy a nodo correspondiente |
Configuración nginx esperada en nebula-vault/docker/nginx.conf (a crear en el repo):
/usr/share/nginx/html/ (output de nx build).try_files $uri /index.html para SPA routing.${API_URL} inyectadas via envsubst en startup (apuntan a datavault-backend en cada ambiente).libraryPipelineNpm() (nuevo, diferido)Para libraries Angular publicadas a Nexus npm registry. Caso aplicable futuro: vault/vault (@nebula/vault).
Parámetros:
libraryPipelineNpm(
artifactName : 'nebula-vault', // nombre del paquete
buildCmd : 'ng build nebula-vault',
nexusRepo : 'centrica-npm', // repositorio Nexus npm (a crear si no existe)
sonar : true
)
Stages: análogas a libraryPipeline Java pero con npm:
npm ci → lint → test → build → npm publish con .npmrc configurado para Nexus.Estado actual: solo se diseña; integración real cuando vault/vault tenga código de negocio (hoy 1 commit scaffold).
develop → qa → main con ramas permanentes.<imagePath>:latest-dev, <imagePath>:latest-qa, <imagePath>:latest (PROD) + tag inmutable <branch>-<sha>-<build>.http://10.110.0.2:8080/multibranch-webhook-trigger/invoke?token=<repo>-webhook con eventos push, tag_push, merge_requests..env con IMAGE_TAG=latest-dev|latest-qa consistente.develop→qa, etc. Aplica igual a Python y Angular.QA_HANDOFF.md / QA_EXECUTION_REPORT.md / QA_CLOSURE.md se producen igual por sprint.| Repo | Gap | Acción |
|---|---|---|
datavault-backend |
Sin Jenkinsfile, sin job multibranch Jenkins, sin webhook GitLab, sin rama qa |
Tras Fase 4 (piloto) |
datavault-backend |
Coverage actual desconocido — revisar pytest --cov baseline |
Fase 3 |
datavault-backend |
Configurar sonar-project.properties para Python |
Fase 3 |
datavault-oais-server |
Sin Dockerfile en repo (corre como python:3.11-slim con bind-mount externo) |
Crear Dockerfile en Fase 2 |
datavault-oais-server |
Verificar si tiene requirements.txt separado del backend |
Fase 2 |
datavault-oais-server |
Sin tests automatizados conocidos | Fase 2/3 — evaluar con equipo si se permite skip o se exige mínimo |
nebula-vault |
Sin Dockerfile | Crear multi-stage en Fase 2 |
nebula-vault |
.npmrc existe — verificar que apunta a Nexus |
Fase 2 — revisar contenido |
nebula-vault |
Sin job multibranch, sin webhook, sin rama qa | Tras Fase 4 |
nebula-vault |
nebula-ui-kit@0.3.4 debe estar publicado y accesible desde Nexus |
Verificar con Edward/Jonathan |
nebula-vault |
E2E con Playwright requiere servicio backend stub — decidir si se ejecuta en pipeline | Fase 3 |
| Compose nodo-01/nodo-02 | Sin bloques para nebula-vault y datavault-oais-server |
Fase 5 (después de validar imagen) |
centrica-pipeline-shared |
Sin entrypoints pythonServicePipeline/angularNxPipeline |
Fase 1 (en curso, branch feature/pipeline-vault) |
| SonarQube | Plugins sonar-python y sonar-typescript instalados? |
Verificar en Fase 3 |
| Jenkins | Plugin NodeJS instalado con Node 22? |
Verificar en Fase 3 |
| Jenkins | Plugin Pyenv Pipeline o equivalente para Python? |
Verificar en Fase 3 |
| Fase | Acción | Owner | Estado |
|---|---|---|---|
| 1 | Diseñar pythonServicePipeline.groovy y angularNxPipeline.groovy en branch feature/pipeline-vault de shared library |
Arquitecto | En curso |
| 2 | Crear Dockerfile faltantes en datavault-oais-server y nebula-vault (PR a develop de cada repo) |
Backend Lead + Frontend Lead | Pendiente |
| 3 | Verificar plugins Jenkins (NodeJS, Python via pyenv o command:python) y plugins Sonar (sonar-python, sonar-typescript) |
DevOps | Pendiente |
| 4 | Pilotos en paralelo: Jenkinsfile + job multibranch + webhook + rama qa para datavault-backend y nebula-vault |
Arquitecto | Pendiente fase 1-3 |
| 5 | Validar E2E del piloto: builds develop SUCCESS, push qa, deploy nodo-02, container healthy | QA Lead + Arquitecto | Pendiente fase 4 |
| 6 | Tagear centrica-pipeline@v1.1.0 con los 2 entrypoints nuevos estabilizados |
Arquitecto | Pendiente fase 5 |
| 7 | Integrar datavault-oais-server (reusa pythonServicePipeline) |
Backend Lead | Pendiente fase 6 |
| 8 | Agregar bloques de compose en nodo-01 y nodo-02 (datavault-backend, datavault-oais-server, nebula-vault) con IMAGE_TAG=latest-dev\|latest-qa |
DevOps + Arquitecto | Pendiente fase 7 |
| 9 | Cuando vault/vault tenga código real, implementar libraryPipelineNpm e integrarlo |
Frontend Lead | Diferido |
| 10 | Retro de la integración: ajustar DoD y políticas si aparecen particularidades de Python o Nx | Arquitecto + equipo | Diferido |
El DEFINITION_OF_DONE corporativo aplica a todos los stacks con estas adaptaciones específicas:
| Categoría | Criterio Java | Criterio Python |
|---|---|---|
| Tests cobertura líneas | ≥ 80% | ≥ 70% (ajustable tras piloto) |
| Tests cobertura branches | ≥ 70% | N/A (Sonar Python no separa branch coverage por defecto) |
| Linter | Sonar code smells | ruff check . (bloquea en v1.1.1+; en v1.1.0 advierte) |
| Type checking | N/A (Java tipa) | mypy opcional (no bloquea inicial) |
| Build local verde | mvn clean verify |
pytest && ruff check . |
| Categoría | Criterio Java | Criterio Angular |
|---|---|---|
| Tests cobertura | ≥ 80% (jacoco) | ≥ 70% (vitest --coverage) |
| Linter | Sonar code smells | nx run-many --target=lint --all |
| E2E | N/A | Playwright en rama qa y main; opcional en develop |
| Build local verde | mvn clean verify |
nx run-many --target=build --all |
| Boundary Nx | N/A | ESLint @nx/enforce-module-boundaries debe estar verde |
| Riesgo | Mitigación |
|---|---|
oais-server no tiene tests; el equipo puede resistirse a agregar coverage |
Para Fase 7, permitir excepción documentada en QA_HANDOFF.md. Plan de incremento progresivo de cobertura |
| Plugins Jenkins (NodeJS, sonar-typescript) no están instalados | Fase 3 hace inventario antes de pilotar. Si faltan, DevOps los instala con downtime corto (≤ 10 min) |
nebula-ui-kit@0.3.4 no está publicado en Nexus, repo nebula-vault no compila |
Coordinar con Edward/Jonathan antes de Fase 4 para confirmar publicación |
| E2E Playwright requiere backend levantado, complica pipeline | Plan A: stub con MSW. Plan B: skip E2E en pipeline y se ejecuta manualmente en sprint |
| Python build time elevado (pip install lento) | Cache de pip en Jenkins (PIP_CACHE_DIR=/var/jenkins_home/cache/pip) |
Nx workspace tarda mucho con run-many --all |
Activar Nx cache (NX_CACHE_DIRECTORY=/var/jenkins_home/cache/nx-<repo>) — afecta solo este repo, no rompe nada |
| Imagen Docker frontend pesada (nginx + dist Angular) | Multi-stage: node:22-alpine build, copia solo dist/ a nginx:alpine final → imagen final ~30 MB |
| Variables de entorno frontend hardcodeadas a un ambiente | Inyectar ${API_URL} en runtime con envsubst en nginx.conf |
GitLab repos
┌────────────────────────────────────────────────────────────────┐
│ Java (22 repos + 3 libs) Python (2 repos) │
│ └─ microservicePipeline() └─ pythonServicePipeline()│
│ └─ libraryPipeline() │
│ Angular Nx (1 app + 1 lib fut)│
│ └─ angularNxPipeline() │
│ └─ libraryPipelineNpm() │
└──────────────────────────┬─────────────────────────────────────┘
│ webhook push/MR
▼
┌──────────────┐
│ Jenkins │ centrica-pipeline-shared
│ (4 execs) │ @v1.0.4 → @v1.1.0
└──────┬───────┘
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Java build Python build Angular build
(Maven) (pip + pytest) (npm + nx + vitest)
│ │ │
└────────┬────────┴────────┬────────┘
▼ ▼
SonarQube QG Docker build+push
│
┌──────────┼──────────┐
▼ ▼ ▼
develop→ qa→ main→
nodo-01 nodo-02 nodo-PROD
:latest- :latest- :v<X.Y.Z>
dev qa
| Versión | Fecha | Autor | Cambio |
|---|---|---|---|
| 1.0 | 2026-05-11 | Carlos Torres | Versión inicial. Plan PROPUESTO (Fase 1 en curso). Diseña 3 entrypoints (pythonServicePipeline, angularNxPipeline, libraryPipelineNpm). Pilotos en paralelo en datavault-backend y nebula-vault. |