npm v12 CI/CD Pipeline Setup: GitHub Actions, Docker, GitLab CI

Why CI Breaks on npm v12

npm v12 flips three defaults that silently kill CI pipelines:

GitHub Actions: Production-Ready Workflow

Here's a complete workflow that handles npm v12's changes — script approval, caching, and smoke tests to catch silent failures.

Step 1: Full CI Workflow with npm v12

name: CI — npm v12 Compatible

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [18, 20, 22, 24]

    steps:
    - uses: actions/checkout@v4

    - uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node }}

    # Pin npm 12 explicitly
    - run: npm install -g npm@12

    # Cache ~/.npm for faster installs (npm v12 compatible)
    - uses: actions/cache@v4
      with:
        path: ~/.npm
        key: npm-${{ runner.os }}-${{ matrix.node }}-${{ hashFiles('**/package-lock.json') }}
        restore-keys: npm-${{ runner.os }}-${{ matrix.node }}-

    # Install with script approval
    - run: npm ci --allow-scripts-pending
      env:
        NPM_CONFIG_ALLOW_SCRIPTS: pending

    # Approve known-safe native modules
    - run: |
        npm approve-scripts node-gyp
        npm approve-scripts sharp
        npm approve-scripts esbuild
        npm approve-scripts bcrypt

    # Verify native modules actually compiled
    - run: node -e "require('sharp'); require('esbuild'); console.log('OK: all native modules loaded')"

    - run: npm test

Step 2: Smoke Test After Install

The most dangerous npm v12 scenario: npm ci succeeds but native modules are missing. Add this smoke test after every install:

# Check that every package in package.json with native bindings actually compiled
node -e "
const pkgs = ['sharp', 'esbuild', 'bcrypt', 'node-gyp'];
for (const p of pkgs) {
  try { require(p); console.log('✓', p); }
  catch(e) { console.error('✗', p, '— NOT COMPILED'); process.exit(1); }
}
console.log('All native modules present');
"

Step 3: Matrix Testing Across npm Versions

Test both npm 11 (current) and npm 12 (future) in your matrix. Catch regressions before the Node.js upgrade forces them:

strategy:
  matrix:
    node: [18, 20, 22]
    npm: [11, 12]

steps:
- uses: actions/setup-node@v4
  with:
    node-version: ${{ matrix.node }}
- run: npm install -g npm@${{ matrix.npm }}
- run: npm ci --allow-scripts-pending
- run: npm approve-scripts node-gyp sharp esbuild
- run: npm test

Dockerfile for npm v12

Your Docker builds need explicit approval of native modules and the C++17 toolchain.

Production Dockerfile

FROM node:22-slim

# npm v12 needs C++17 for native modules
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential python3 make gcc g++ \
    && rm -rf /var/lib/apt/lists/*

# Pin npm version
RUN npm install -g npm@12

WORKDIR /app

# Copy package files first (layer caching)
COPY package.json package-lock.json ./

# Install with pending scripts, then approve known-safe ones
RUN npm ci --allow-scripts-pending && \
    npm approve-scripts node-gyp sharp esbuild bcrypt

# Verify native modules built
RUN node -e "require('sharp'); require('esbuild'); console.log('Native modules OK')"

COPY . .

EXPOSE 3000
CMD ["node", "index.js"]

Multi-Stage Build: Generate Allowlist

For teams that want zero manual approvals, generate the allowlist in a builder stage:

# Stage 1: Generate allowlist
FROM node:22-slim AS allowlist-gen
RUN npm install -g npm@12
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --allow-scripts-pending 2>&1 | \
    grep -oP 'package \K[^ ]+(?= wants to run)' | sort -u > scripts-allowlist.txt

# Stage 2: Production with allowlist
FROM node:22-slim
RUN apt-get update && apt-get install -y build-essential python3 && \
    rm -rf /var/lib/apt/lists/*
RUN npm install -g npm@12
WORKDIR /app
COPY --from=allowlist-gen /app/scripts-allowlist.txt ./
COPY package.json package-lock.json ./
RUN npm ci && \
    while read pkg; do npm approve-scripts "$pkg"; done < scripts-allowlist.txt
COPY . .
CMD ["node", "index.js"]

GitLab CI Configuration

# .gitlab-ci.yml — npm v12 Compatible
image: node:22

variables:
  NPM_VERSION: "12"

before_script:
  - npm install -g npm@${NPM_VERSION}
  # Cache ~/.npm across jobs
  - npm config set cache .npm-cache

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .npm-cache/
    - node_modules/

test:
  script:
    - npm ci --allow-scripts-pending
    - npm approve-scripts node-gyp sharp esbuild
    - node -e "require('sharp'); require('esbuild'); console.log('OK: native modules verified')"
    - npm test

lint:
  script:
    - npm ci
    - npm run lint

# Check for Git deps in lockfile (prevent surprise CI failures)
check-git-deps:
  script:
    - ! grep -q 'git+https://' package-lock.json && echo "OK: no git deps" || (echo "FAIL: Git deps found in lockfile — will break npm v12" && exit 1)

Common CI Failures & Fixes

FAQ

Related Guides: