GitHub Actions CI/CD: Build a Complete Node.js Pipeline (2026)

A CI/CD pipeline that catches bugs before deploy, builds reproducible Docker images, and ships to production with zero downtime is table stakes for any serious Node.js project. GitHub Actions makes all of this achievable with YAML configuration — but the defaults are slow, insecure, and fragile. This guide shows you every pattern you need, from caching to rollback.

Looking for production-ready Node.js templates? Browse WOWHOW Tools and the full product catalog for starter kits with CI/CD baked in.

Workflow Basics

Every workflow lives in .github/workflows/. The file name becomes the workflow name in the UI. Events trigger runs; jobs define what runs; steps are the individual commands.

# .github/workflows/ci.yml
name: CI

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

# cancel in-progress runs for the same branch
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: Test
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage

Matrix Builds: Test Across Node Versions

jobs:
  test-matrix:
    name: Test Node ${{ matrix.node }} / ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        node: ['20', '22']
        os: [ubuntu-24.04, windows-latest]
        exclude:
          # skip windows + node 20 combination
          - os: windows-latest
            node: '20'

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'
      - run: npm ci
      - run: npm test

Caching for Speed

Without caching, npm ci downloads everything from npm on every run. With caching, subsequent runs skip the download entirely — cutting minutes off your pipeline.

steps:
  - uses: actions/checkout@v4

  # node setup with built-in npm cache
  - uses: actions/setup-node@v4
    with:
      node-version: '22'
      cache: 'npm'             # hashes package-lock.json automatically

  # manual cache for build artifacts (e.g. Next.js .next/cache)
  - name: Cache build artifacts
    uses: actions/cache@v4
    with:
      path: .next/cache
      key: nextjs-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
      restore-keys: |
        nextjs-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}-
        nextjs-${{ runner.os }}-

  - run: npm ci
  - run: npm run build

Docker Build and Push

jobs:
  build-push:
    name: Build & Push Docker Image
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      packages: write        # for GitHub Container Registry

    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=sha,prefix=sha-
            type=ref,event=branch
            type=semver,pattern={{version}}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha        # GitHub Actions cache for layers
          cache-to: type=gha,mode=max
          build-args: |
            BUILD_DATE=${{ github.event.head_commit.timestamp }}
            GIT_SHA=${{ github.sha }}

Deploying to a VPS via SSH

  deploy:
    name: Deploy to Production
    needs: [test-matrix, build-push]
    runs-on: ubuntu-24.04
    environment:
      name: production
      url: https://myapp.example.com
    if: github.ref == 'refs/heads/main'

    steps:
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          port: 22
          script: |
            set -e
            cd /opt/myapp

            # pull latest image
            echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
            docker pull ghcr.io/${{ github.repository }}:sha-${{ github.sha }}

            # snapshot last-good image before swapping
            docker tag ghcr.io/${{ github.repository }}:latest                        ghcr.io/${{ github.repository }}:last-good 2>/dev/null || true

            # atomic swap
            docker compose up -d --no-deps app
            docker image prune -f

Secrets and Environment Variables

# NEVER hardcode secrets. Use GitHub Secrets.
# Settings → Secrets and variables → Actions

jobs:
  deploy:
    steps:
      - name: Run migrations
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
          REDIS_URL: ${{ secrets.REDIS_URL }}
        run: npm run db:migrate

      # pass to Docker build-arg (does NOT embed in final image layers if used correctly)
      - uses: docker/build-push-action@v6
        with:
          build-args: |
            NEXT_PUBLIC_API_URL=${{ vars.NEXT_PUBLIC_API_URL }}
          secrets: |
            DATABASE_URL=${{ secrets.DATABASE_URL }}

Reusable Workflows

Reusable workflows let you define a workflow once and call it from multiple repositories or jobs. They are the DRY principle for CI/CD.

# .github/workflows/_reusable-test.yml
on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: '22'
    secrets:
      DATABASE_URL:
        required: true

jobs:
  test:
    runs-on: ubuntu-24.04
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm test
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

# .github/workflows/ci.yml — calling the reusable workflow
jobs:
  test:
    uses: ./.github/workflows/_reusable-test.yml
    with:
      node-version: '22'
    secrets:
      DATABASE_URL: ${{ secrets.DATABASE_URL }}

Self-Hosted Runners

# run on your own hardware for faster builds or private network access
jobs:
  deploy-internal:
    runs-on: self-hosted         # uses any runner with no labels
    # OR target specific runners:
    runs-on: [self-hosted, linux, x64, production]

    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run deploy:internal
        env:
          INTERNAL_API_URL: ${{ secrets.INTERNAL_API_URL }}

Register a self-hosted runner at Settings → Actions → Runners → New self-hosted runner. The runner process runs on your machine and polls GitHub for jobs. Label runners to control which jobs run where.

A Complete Pipeline: Test, Build, Deploy, Verify

# .github/workflows/deploy.yml
name: Deploy Production

on:
  push:
    branches: [main]

concurrency:
  group: deploy-production
  cancel-in-progress: false

jobs:
  test:
    uses: ./.github/workflows/_reusable-test.yml
    secrets: inherit

  build:
    needs: test
    runs-on: ubuntu-24.04
    outputs:
      image-tag: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: type=sha,prefix=sha-
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy:
    needs: build
    runs-on: ubuntu-24.04
    environment: production
    steps:
      - uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            cd /opt/myapp
            IMAGE="ghcr.io/${{ github.repository }}:sha-${{ github.sha }}"
            docker pull "$IMAGE"
            IMAGE="$IMAGE" docker compose up -d --no-deps app

  verify:
    needs: deploy
    runs-on: ubuntu-24.04
    steps:
      - name: Health check
        run: |
          for i in 1 2 3 4 5; do
            STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://myapp.example.com/healthz)
            if [ "$STATUS" = "200" ]; then
              echo "Health check passed"
              exit 0
            fi
            echo "Attempt $i: got $STATUS, retrying in 10s..."
            sleep 10
          done
          echo "Health check failed after 5 attempts"
          exit 1

People Also Ask

How do I prevent GitHub Actions from running on draft pull requests?

Add a filter to your pull_request trigger: types: [opened, synchronize, reopened]. Draft PRs only trigger on opened and converted_to_draft — removing opened from the list does not help since drafts fire on it. The correct approach is to add a conditional: if: github.event.pull_request.draft == false on the job or workflow level.

What is the difference between secrets.GITHUB_TOKEN and a personal access token?

GITHUB_TOKEN is automatically provisioned by GitHub Actions for every run — it is scoped to the current repository and expires when the run ends. It is sufficient for pushing Docker images to GHCR, creating releases, and commenting on PRs. A PAT (personal access token) or fine-grained token is needed when you need to access other repositories, create webhooks, or perform actions that exceed the default token’s permissions. Always prefer GITHUB_TOKEN where possible — it is the principle of least privilege.

How do I speed up npm install in GitHub Actions?

Use actions/setup-node with cache: 'npm' — this caches the npm global cache keyed on package-lock.json. Also use npm ci (not npm install) in CI — it skips the dependency resolution step, uses the lockfile directly, and is 2–3x faster. For monorepos, cache the individual package directories with actions/cache using a hash of all package-lock.json files as the key.