GitLab CI Pipeline for Node.js Projects

Building a Node.js CI Pipeline in GitLab

A well-structured Node.js pipeline typically has four stages: dependency installation, linting, testing, and building. This separation ensures fast feedback — a lint failure stops the pipeline before expensive test and build steps run.

Pipeline Structure

stages:
  - install
  - lint
  - test
  - build

variables:
  NODE_ENV: test

install_deps:
  stage: install
  image: node:20-alpine
  script:
    - npm ci
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
    policy: push
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour

lint:
  stage: lint
  image: node:20-alpine
  script:
    - npm run lint
  needs:
    - install_deps

test:
  stage: test
  image: node:20-alpine
  script:
    - npm test -- --coverage
  needs:
    - install_deps
  artifacts:
    paths:
      - coverage/
    expire_in: 30 days

build:
  stage: build
  image: node:20-alpine
  script:
    - npm run build
  needs:
    - install_deps
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

Key Design Decisions

npm ci instead of npm install: The ci command installs exact versions from package-lock.json, is faster, and deletes node_modules before installing. This guarantees reproducible builds.

Caching node_modules/: The cache key uses ${CI_COMMIT_REF_SLUG} so each branch gets its own cache. The install job pushes to the cache, and downstream jobs can pull from it.

Artifacts vs. Cache: Artifacts are used to pass node_modules/ between jobs in the same pipeline (reliable, guaranteed delivery). Cache is used across pipeline runs on the same branch (best-effort, speeds up subsequent runs).

DAG with needs: Instead of waiting for all jobs in a stage, lint, test, and build each declare they need only install_deps. This lets them start as soon as installation finishes, even if other install-stage jobs exist.