How to Set Up a CI/CD Pipeline for a Node.js App: Step-by-Step Guide with GitHub Actions

Shipping a Node.js application without an automated pipeline in 2026 is like driving a car without a seatbelt. It works, until it doesn’t. A well-configured CI/CD pipeline for Node.js catches bugs before they reach production, removes the manual “works on my machine” drama, and lets your team focus on building features instead of babysitting deployments.

In this guide, we walk through the exact steps to set up a complete CI/CD pipeline for a Node.js application using GitHub Actions, including real YAML configurations, deployment to a cloud host, and the pitfalls most tutorials forget to mention.

What You’ll Build

By the end of this tutorial, you’ll have a pipeline that automatically:

Runs on every push and pull request
Installs dependencies with caching
Lints your code
Runs your test suite
Builds your application
Deploys to a cloud host (we’ll use a generic VPS/cloud server example)

Prerequisites

A Node.js project (version 20 LTS or 22 LTS recommended in 2026)
A GitHub repository
A cloud host (DigitalOcean, AWS EC2, Render, Railway, or similar)
Basic knowledge of Git and the terminal

Step 1: Understand the CI/CD Pipeline Stages

Before writing a single line of YAML, let’s clarify what each stage does:

Stage	Purpose	Tools
Checkout	Pull the code from the repo	actions/checkout
Install	Install dependencies with caching	actions/setup-node, npm/yarn/pnpm
Lint	Enforce code style	ESLint, Biome
Test	Run unit and integration tests	Jest, Vitest, Node test runner
Build	Compile TS or bundle assets	tsc, esbuild, webpack
Deploy	Push to production	SSH, Docker, cloud CLI

Step 2: Prepare Your Node.js Project

Make sure your package.json contains the scripts the pipeline will call:

{
  "name": "my-node-app",
  "version": "1.0.0",
  "scripts": {
    "start": "node dist/index.js",
    "dev": "node --watch src/index.js",
    "lint": "eslint .",
    "test": "node --test",
    "build": "tsc"
  },
  "engines": {
    "node": ">=20"
  }
}

Pro tip: The engines field is more than documentation. Some hosts and CI tools read it to determine the runtime version.

Step 3: Create Your First GitHub Actions Workflow

Inside your repository, create the folder .github/workflows/ and add a file named ci.yml:

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20.x, 22.x]

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build application
        run: npm run build

What This Workflow Does

Triggers on pushes to main/develop and on pull requests targeting main
Tests against both Node 20 and 22 in parallel (the matrix strategy)
Caches node_modules via the cache: 'npm' option, cutting build time significantly
Uses npm ci instead of npm install for reproducible, lockfile-strict installs

Step 4: Add Continuous Deployment

Now let’s extend the pipeline to deploy automatically when code lands on main. Create a second workflow at .github/workflows/deploy.yml:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: []
    environment: production

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Install production dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Deploy via SSH
        uses: appleboy/[email protected]
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            cd /var/www/my-node-app
            git pull origin main
            npm ci --omit=dev
            npm run build
            pm2 reload my-node-app

Storing Secrets Safely

Never hardcode credentials. In your GitHub repository, go to Settings > Secrets and variables > Actions and add:

SERVER_HOST: your server IP or domain
SERVER_USER: the SSH user (often deploy or ubuntu)
SSH_PRIVATE_KEY: the private key paired with a public key on the server

Step 5: Alternative Deploy Targets

Not everyone runs their own VPS. Here are common alternatives:

Deploy to Render or Railway

Both platforms auto-deploy on push to your default branch. You only need the CI part of the workflow. Add a deploy hook URL as a secret and trigger it with curl:

      - name: Trigger Render deploy
        run: curl -X POST ${{ secrets.RENDER_DEPLOY_HOOK }}

Deploy to AWS via Docker

Build a Docker image, push to ECR, and update an ECS service or App Runner. This works well when you already containerize your app.

Deploy to Vercel or Netlify

For Node.js APIs running as serverless functions, the official Vercel/Netlify CLIs can be triggered directly inside the workflow.

Step 6: Add a Status Badge

Show off your green builds. Add this to your README.md:

![CI](https://github.com/your-username/your-repo/actions/workflows/ci.yml/badge.svg)

Common Pitfalls to Avoid

After helping dozens of teams set this up, here are the mistakes we see most often:

Using npm install instead of npm ci: npm install can mutate your lockfile and introduce non-deterministic builds.
Skipping the cache: Without dependency caching, every workflow run wastes 30 to 90 seconds reinstalling identical packages.
Running tests against only one Node version: If your library or app supports multiple LTS versions, test them all in a matrix.
Storing .env files in the repo: Use GitHub Secrets and inject env vars at runtime.
No branch protection: Enforce that CI must pass before a PR can be merged. Configure this under Settings > Branches.
Deploying without a health check: Always verify the app responds after deploy. A failed deploy that doesn’t roll back is worse than no deploy.
Ignoring workflow concurrency: Use concurrency: to cancel in-progress runs when a new commit arrives. Saves CI minutes.

Bonus: Concurrency Configuration

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Going Further: Production-Grade Enhancements

Add code coverage with c8 or nyc and upload to Codecov.
Run security audits with npm audit --audit-level=high as a separate job.
Use environments with required reviewers for production deploys.
Implement blue-green or canary deployments if downtime matters.
Add Slack or Discord notifications on deploy success/failure.

Final Thoughts

A solid CI/CD pipeline for a Node.js app isn’t just a nice-to-have in 2026. It’s the baseline. With GitHub Actions, you can go from zero to fully automated testing and deployment in under an hour. Start simple, iterate, and treat your pipeline as code that deserves the same review and care as your application.

At Coding4.net, we help teams design, audit, and optimize their CI/CD workflows for Node.js, .NET, and beyond. If you want a hand wiring up your pipeline, get in touch.

FAQ

What is the difference between CI and CD?

Continuous Integration (CI) is the practice of automatically testing and validating code on every commit. Continuous Delivery/Deployment (CD) extends that by automatically shipping the validated build to staging or production.

Is GitHub Actions free for Node.js projects?

Yes. Public repositories get unlimited free minutes. Private repos get a generous monthly free tier (2,000 minutes on the Free plan as of 2026), and additional minutes are billed per usage.

Should I use Docker in my Node.js CI/CD pipeline?

Docker adds reproducibility and makes deployments host-agnostic. If you plan to run on Kubernetes, ECS, or any container platform, yes. For simple VPS deploys with PM2, you can skip it.

How do I handle environment variables in GitHub Actions?

Use GitHub Secrets for sensitive values and reference them as ${{ secrets.MY_VAR }}. For non-sensitive config, use GitHub Variables or define them inline with the env: key.

What’s better: npm, yarn, or pnpm in CI?

All three work fine. pnpm is generally the fastest and most disk-efficient, especially in monorepos. Stick with whatever your project already uses, and make sure to cache the right store path.

How do I rollback a failed deployment?

The simplest approach is to keep the previous build artifact and add a manual workflow that redeploys it. Advanced setups use blue-green deployments or container image tags that you can pin to a previous version.