GitHub Actions: Node.js CI/CD Pipeline

TL;DR

• Bottom line: GitHub Actions provides native CI/CD for Node.js projects with matrix testing across versions, built-in npm caching, and deployment to any target -- all configured in a single YAML file at .github/workflows/.
• Key tool/command: actions/setup-node@v4 with cache: 'npm' and npm ci for deterministic installs.
• Watch out for: Using npm install instead of npm ci in workflows -- it's slower, non-deterministic, and can modify package-lock.json.
• Works with: Node.js 18.x, 20.x, 22.x on ubuntu-latest, windows-latest, macos-latest runners.

Constraints

• Always use npm ci instead of npm install -- npm ci deletes node_modules/ first, installs exact versions from package-lock.json, and fails if the lockfile is out of sync.
• Pin action versions to major tags (e.g., actions/checkout@v4) -- never use @main or floating tags in production workflows.
• Node.js 16 is EOL and removed from GitHub-hosted runners since September 2023 -- minimum supported is Node.js 18.
• Set explicit permissions block with least-privilege access -- default GITHUB_TOKEN permissions may be too broad.
• Never echo or log secrets -- use ::add-mask:: for dynamic values and store credentials in GitHub Secrets only.

Quick Reference

Decision Tree

START
├── Single Node.js version project?
│   ├── YES → Use fixed node-version (e.g., 20) with npm ci + test + build
│   └── NO ↓
├── Library published to npm?
│   ├── YES → Matrix strategy [18, 20, 22] + publish job with NODE_AUTH_TOKEN
│   └── NO ↓
├── Monorepo with multiple packages?
│   ├── YES → Use workspaces, npm ci at root, run tests per package
│   └── NO ↓
├── Deploy to cloud provider?
│   ├── YES → Add deploy job with environment protection + needs: [test, build]
│   └── NO ↓
└── DEFAULT → Basic CI: checkout → setup-node → npm ci → npm test

Step-by-Step Guide

1. Create the workflow file

Create .github/workflows/ci.yml in your repository. GitHub automatically detects and runs workflows from this directory. [src1]

name: Node.js CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Verify: Push to GitHub → go to Actions tab → see workflow run with 3 parallel matrix jobs.

2. Add linting and build steps

Extend the workflow with lint and build steps that run after dependency installation. [src5]

      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build

Verify: Deliberately introduce a lint error → push → workflow should fail at the lint step.

3. Configure npm caching

The cache: 'npm' option on setup-node caches the global npm cache directory (~/.npm). It requires package-lock.json to exist. [src2]

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

Verify: Check workflow logs for "Cache hit" message on the second run.

4. Add test coverage reporting

Upload coverage reports as artifacts for review. [src1]

      - run: npx jest --ci --coverage
      - name: Upload coverage
        if: matrix.node-version == 20
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: coverage/
          retention-days: 14

Verify: After workflow completes → Artifacts section shows coverage-report download.

5. Add deployment with environment protection

Create a deploy job that only runs after tests pass on the main branch. [src7]

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Deploy
        run: npx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Verify: Create a production environment in Settings → Environments → add required reviewers.

6. Publish to npm registry

For libraries, add a publish job triggered on release. [src2]

  publish:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name == 'release'
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Verify: Create a GitHub Release → Actions tab shows publish job → check npmjs.com for new version.

Code Examples

Complete CI/CD workflow with matrix, lint, test, build, and deploy

# .github/workflows/ci.yml
# Input:  Node.js project with package.json, package-lock.json
# Output: Tested, built, and deployed application

name: Node.js CI/CD

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint

  test:
    runs-on: ubuntu-latest
    needs: lint
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --ci --coverage
      - name: Upload coverage
        if: matrix.node-version == 20
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: build-output
          path: dist/

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: build-output
          path: dist/
      - name: Deploy to production
        run: echo "Deploy dist/ to your target"
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

npm publish workflow triggered on release

# .github/workflows/publish.yml
# Input:  npm package with package.json
# Output: Published package on npmjs.com

name: Publish to npm

on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm test
      - run: npm publish --provenance --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Monorepo CI with workspaces

# .github/workflows/monorepo.yml
# Input:  npm workspaces monorepo
# Output: All packages tested and built

name: Monorepo CI

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm test --workspaces --if-present
      - run: npm run build --workspaces --if-present

Anti-Patterns

Wrong: Using npm install instead of npm ci

# ❌ BAD — npm install can modify package-lock.json and is non-deterministic
steps:
  - run: npm install
  - run: npm test

Correct: Using npm ci for deterministic installs

# ✅ GOOD — npm ci is faster, deterministic, and fails if lockfile is out of sync
steps:
  - run: npm ci
  - run: npm test

Wrong: Not pinning action versions

# ❌ BAD — @main can change at any time, breaking your workflow
steps:
  - uses: actions/checkout@main
  - uses: actions/setup-node@main

Correct: Pinning to major version tags

# ✅ GOOD — @v4 is stable and receives only non-breaking updates
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4

Wrong: Caching node_modules directly

# ❌ BAD — node_modules may contain platform-specific binaries, cache is fragile
- uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-modules-${{ hashFiles('package-lock.json') }}
- run: npm install

Correct: Using built-in cache on setup-node

# ✅ GOOD — caches ~/.npm global cache, works across Node versions
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'npm'
- run: npm ci

Wrong: Running deploy on pull requests

# ❌ BAD — deploys on every PR, including from forks (security risk)
deploy:
  needs: test
  runs-on: ubuntu-latest
  steps:
    - run: npx deploy-command
      env:
        API_KEY: ${{ secrets.API_KEY }}

Correct: Restricting deploy to main branch pushes

# ✅ GOOD — only deploys on push to main, with environment protection
deploy:
  needs: test
  runs-on: ubuntu-latest
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  environment: production
  steps:
    - run: npx deploy-command
      env:
        API_KEY: ${{ secrets.API_KEY }}

Common Pitfalls

• Missing package-lock.json: npm ci requires package-lock.json to exist. Fix: run npm install locally and commit the lockfile. [src2]
• Node version mismatch: Workflow uses Node 22 but app only works on Node 18. Fix: match node-version to .nvmrc or use node-version-file: '.nvmrc'. [src1]
• Cache not restoring: Cache key includes OS and lockfile hash -- any lockfile change invalidates the cache. Fix: expected behavior; npm ci with cache miss still works. [src4]
• Tests pass locally but fail in CI: Often caused by timezone differences (CI uses UTC), missing env vars, or case-sensitive file systems on Linux. Fix: set TZ: UTC in env. [src5]
• Workflow not triggering: Branch names in on.push.branches must match exactly. Fix: check branch name casing and use ** for wildcards. [src3]
• Secrets not available in fork PRs: GitHub does not expose secrets to workflows triggered by PRs from forks. Fix: use pull_request_target with caution. [src6]

Diagnostic Commands

# Check installed Node.js version in workflow
node --version

# Verify npm ci installed exact lockfile versions
npm ls --depth=0

# List all GitHub Actions workflow files
ls -la .github/workflows/

# Validate workflow YAML locally (requires actionlint)
actionlint .github/workflows/ci.yml

# Check workflow run status via CLI
gh run list --workflow=ci.yml --limit=5

# View specific workflow run logs
gh run view <run-id> --log

# Check available secrets (names only)
gh secret list

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• GitHub-hosted runners have a 6-hour job timeout and 35-day log retention. Self-hosted runners have no timeout by default.
• The npm ci command deletes the entire node_modules/ folder before installing, so caching node_modules/ is pointless when using npm ci.
• Free tier GitHub Actions provides 2,000 minutes/month for private repos. Public repos get unlimited minutes.
• actions/upload-artifact@v4 artifacts expire after 90 days by default. Set retention-days to control this.
• Workflow files must be on the default branch to appear in the Actions tab for workflow_dispatch triggers.