Lerna CI/CD Production Deployment - AI-Optimized Knowledge Base

Critical Configuration Requirements

Authentication Setup (BREAKING: Wrong config causes 4+ hour debugging sessions)

Failure Mode: npm ERR! 401 Unauthorized - Silent failure with deprecated auth methods
Root Cause: Lerna moved from npm_config__auth to _authToken without documentation updates

Working Configuration:

env:
  NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

steps:
- name: "Configure npm"
  run: |
    npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
    npm config set registry https://registry.npmjs.org/

Critical: Use _authToken NOT npm_config__auth (deprecated, causes phantom failures)

Git Configuration (CRITICAL: CI fails with cryptic git errors)

Failure Mode: Error: Command failed with exit code 128: git diff --name-only
Root Cause: GitHub Actions shallow clone by default, Lerna needs full history

Required Fix:

- uses: actions/checkout@v3
  with:
    fetch-depth: 0  # Required for Lerna change detection

Docker Build Optimization

Performance Impact

• Problem: Change one comment, rebuild everything (15+ minute builds)
• Solution: Multi-stage builds with dependency caching
• Time Savings: From 15+ minutes to 2-5 minutes

Optimized Dockerfile Structure:

# Stage 1: Cache dependencies separately
FROM node:18-alpine AS deps
WORKDIR /app
COPY package*.json lerna.json ./
COPY packages/*/package*.json ./packages/
RUN npm ci --only=production

# Stage 2: Build specific package only
FROM deps AS build
COPY packages/api ./packages/api
RUN npx lerna run build --scope=@company/api

Critical: Copy dependencies before source code to leverage Docker layer caching

Package Publishing Order and Dependency Management

High-Severity Failure Scenario

Impact: 30-60 seconds of broken installs, production service degradation
Cause: Publishing packages before their dependencies are available

Publishing Sequence Failure:

1. Update @company/utils from 1.2.0 to 1.3.0
2. Update @company/ui to depend on @company/utils@^1.3.0
3. Publish @company/ui@2.1.0 first (CRITICAL ERROR)
4. Users install UI 2.1.0, get dependency error for utils 1.3.0
5. Production alerts at 11pm

Automated Solution:

{
  "version": "independent",
  "npmClient": "npm",
  "command": {
    "publish": {
      "conventionalCommits": true,
      "message": "chore(release): publish",
      "registry": "https://registry.npmjs.org"
    }
  }
}

Key: Lerna automatically calculates dependency graph and publishes in correct order

Resource Requirements and Scaling Thresholds

Nx Cloud Cost Analysis

Break-even Point: Teams with 10+ developers, builds exceeding 15+ minutes
Cost Range: $500+/month for large monorepos after free tier
Alternative: Local caching sufficient for builds under 5 minutes

Worth the Cost When:

• Build times exceed 15+ minutes locally
• CI builds block developer productivity
• Team has 10+ developers working on monorepo daily

Not Worth It When:

• Total build time under 5 minutes
• Small team (< 5 developers)
• Budget constraints outweigh time savings

Build Performance Optimization

Selective Deployment Configuration:

- name: Detect changes
  uses: dorny/paths-filter@v2
  id: changes
  with:
    filters: |
      api:
        - 'packages/api/**'
      auth:
        - 'packages/auth/**'

- name: Deploy API
  if: steps.changes.outputs.api == 'true'
  run: npx lerna run deploy --scope=@company/api

Critical Warning: Include dependencies with --include-dependencies flag to prevent broken deployments

Production Deployment Failure Modes and Recovery

Zero-Downtime Deployment Requirements

Risk: 5+ minutes of 500 errors during simultaneous package deployment
Solution: Blue-green deployment with staged rollout

Emergency Rollback Strategies:

Infrastructure Rollback (< 2 minutes):

# Kubernetes
kubectl rollout undo deployment/api-service

# Docker containers
docker service rollback api-service

NPM Package Rollback (5-10 minutes):

# Find last working version
git log --oneline --grep="chore(release): publish"

# Revert and republish
git revert <commit-hash>
npx lerna publish from-git --yes

Monitoring and Debugging Production Issues

Problem: 8 packages deployed simultaneously, unclear which broke production
Solution: Package-specific error tracking and semantic versioning tags

Required Tooling:

• Semantic versioning tags for release tracking
• Conventional commits for automated changelog generation
• Package-specific error monitoring (Sentry, DataDog)

Security and Secrets Management

Critical Security Requirements

Failure Modes:

• API keys in Docker images
• Database passwords committed to git
• Auth tokens in package.json

Secure Configuration:

- name: Deploy with secrets
  run: |
    kubectl create secret generic app-secrets \
      --from-literal=DATABASE_URL=${{ secrets.DATABASE_URL }} \
      --from-literal=API_KEY=${{ secrets.API_KEY }}
    
    npx lerna run deploy --scope=@company/api
  env:
    NODE_ENV: production

Rule: Inject secrets at runtime, never at build time

Common Production Deployment Failures

Startup Failures After Successful Deployment

Debug Process:

# Enable verbose Lerna logging
npx lerna run deploy --loglevel silly

# Check for missing environment variables
npx lerna run health-check --parallel

Common Causes:

• Missing environment variables (database URLs, API keys)
• Wrong Node.js version in production vs development
• Dependencies installed with --only=production missing devDependencies used at runtime
• File paths that work locally but break in containers

Version Conflict Resolution

Development Branch Workflow:

# Creates 1.2.0-beta.0, 1.2.0-beta.1, etc.
npx lerna version --conventional-prerelease --preid beta --yes

Main Branch Workflow:

# Converts 1.2.0-beta.1 to 1.2.0
npx lerna version --conventional-graduate --yes

Critical: Don't manually merge version bumps between branches - Lerna handles version progression automatically

Cost Optimization Strategies

CI/CD Cost Management

Optimization Tactics:

• GitHub-hosted runners for small builds, self-hosted for heavy workloads
• Automatic Docker image cleanup: docker system prune --all --filter "until=168h"
• Artifact retention policies to delete old build artifacts

Warning: Monitor costs continuously - debug logging in production can increase AWS bills from hundreds to thousands without notice

Dependency Change Detection

Correct Change Detection

# Wrong - misses dependent packages
npx lerna run deploy --since HEAD~1

# Right - includes dependencies
npx lerna run deploy --since HEAD~1 --include-dependencies

Critical: Dependency graph detection is core Lerna functionality - if Package A depends on Package B and B changes, both need deployment even if A's code is unchanged

Recovery from Partial Publishing Failures

Scenario: Package publishing fails mid-process, some packages published, others stuck
Solution:

npx lerna publish from-git

Function: Reads git tags to determine what needs publishing, recovers from partial failures automatically