Saltar al contenido principal

CI/CD Caching — Referencia para equipo de Infra

Audiencia: Este documento es referencia técnica para el equipo de Infraestructura que gestiona el repo central de CI/CD (<<REPO_CI_INFRA>>).

Los desarrolladores no escriben ni modifican configuraciones de CI/CD en sus repos. Ver ci-arquitectura para entender el modelo completo.

Contexto de la arquitectura​

En Wiedii, los pipelines CI/CD se definen en el repo central de infra (<<REPO_CI_INFRA>>), no en los repos de desarrollo. La configuración se aplica a cada proyecto desde GitLab → Settings → CI/CD → General pipelines.

Los jobs se ejecutan en servidores remotos especializados via conectores — el servidor de GitLab solo orquesta.

Stack de herramientas en pipelines​

HerramientaRol en CI
miseActivar versiones exactas de runtimes (bun, node, python…)
bunRuntime JS, instalación de dependencias, ejecutar scripts
bun install --frozen-lockfileInstalación reproducible — obligatorio en CI

Patrones de caching recomendados​

Variables de cache (definir a nivel de pipeline)​

variables:
  MISE_DATA_DIR:        "$CI_PROJECT_DIR/.cache/mise"
  BUN_INSTALL_CACHE_DIR: "$CI_PROJECT_DIR/.cache/bun"

Cache compartido entre jobs​

cache:
  key:
    files:
      - mise.toml
      - bun.lock
  paths:
    - .cache/mise/
    - .cache/bun/
    - node_modules/

La clave del cache combina el hash de mise.toml y bun.lock:

  • Si cambia mise.toml → se invalida el cache de mise
  • Si cambia bun.lock → se invalida el cache de bun y node_modules
  • Sin cambios → se reutiliza el cache completo

Cache por job específico (ESLint, TypeScript)​

lint:eslint:
  cache:
    - key:
        files: [bun.lock]
      paths: [.cache/bun/, node_modules/]
    - key: eslint-$CI_COMMIT_REF_SLUG
      paths: [.eslintcache]
  script:
    - bun eslint . --cache --cache-location .eslintcache

lint:typescript:
  script:
    - bun tsc --noEmit --incremental

Nx monorepos — affected commands​

variables:
  GIT_DEPTH: "0"   # obligatorio para que nx affected calcule correctamente el diff

lint:affected:
  script:
    - bun nx affected -t lint --base=origin/develop

test:affected:
  script:
    - bun nx affected -t test --base=origin/develop

build:affected:
  script:
    - bun nx affected -t build --base=origin/develop

GIT_DEPTH: "0" es necesario para que Nx tenga el historial git completo y pueda calcular correctamente qué proyectos cambiaron.

Reglas de caching​

  1. Siempre cachear .cache/mise/ con clave derivada de mise.toml
  2. Siempre cachear .cache/bun/ y node_modules/ con clave derivada de bun.lock
  3. Siempre usar bun install --frozen-lockfile — nunca bun install sin flag en CI
  4. Usar --cache en ESLint e --incremental en TypeScript para cache incremental
  5. En Nx: configurar GIT_DEPTH: "0" a nivel de pipeline, no de job

Artifacts​

build:
  stage: build
  script:
    - bun run build
  artifacts:
    paths:
      - dist/
      - build/
    expire_in: 1 week   # no acumular artifacts indefinidamente

Los artifacts de producción (imágenes Docker, binarios) siguen el proceso de build en los servidores especializados — su configuración específica vive en el repo de infra.

Conexión con protección de ramas​

Los pipelines deben pasar antes de que GitLab permita el merge. Configurar en GitLab → Settings → Repository → Protected branches:

  • Rama main: require passing pipeline + aprobación
  • Rama develop: require passing pipeline

Ver branch-protection para la configuración completa.

Referencias​

  • ci-arquitectura — modelo completo: repo de infra, runners remotos, qué hace cada equipo
  • branch-protection — protección de ramas y requisito de pipeline verde
  • nx-monorepo — política de workspace Nx y uso de affected