Automate Testing and Deployment for Your Node.js Project with GitHub Actions: A Beginner's Guide

Are you tired of manually running tests after every commit or handling deployments yourself? For Node.js developers, repetitive tasks can be time-consuming. GitHub Actions lets you automate the testing and deployment process with just a push or pull request. Today, we'll dive into setting up a fundamental workflow YAML, designed for newcomers to use instantly in real-world applications.

1) Getting Started: Essential Requirements for Your Project

Checklist

• Ensure your package.json includes a test script.
• Example: "test": "jest" or "test": "vitest run"
• It’s recommended to use the LTS version of Node (e.g., 20).
• For deployment, we'll demonstrate using SSH to execute a script on your server.

Sample package.json (Key Parts)

{
  "scripts": {
    "test": "npm run lint && npm run unit",
    "lint": "eslint .",
    "unit": "vitest run",
    "build": "tsc -p ."
  }
}

2) Create an Automated Testing Workflow (Highly Recommended First Step)

Create a file in the root of your repository:

• .github/workflows/ci.yml

Basic CI Workflow (Automatic Test Execution)

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [20]

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

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

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Key Points

• Using on: pull_request enables automatic validation when creating a PR.
• npm ci ensures stable installation based on the lockfile, preferred over npm install.
• cache: "npm" speeds up re-runs.

3) Linking Tests with Deployment: “Deploy if Tests Pass”

This is where automation shines. The setup is simple:

• Connects to CD (Continuous Deployment) if CI (Continuous Integration) tests succeed. You can add the deployment job to the same file or separate it. Initially, keeping it in one file is easier to understand.

Deploying After Successful Tests (Job Linking)

name: CI-CD

on:
  push:
    branches: [ "main" ]

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
      - run: npm run build

  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: ${{ success() }}

    steps:
      - name: Deploy via SSH
        env:
          SSH_HOST: ${{ secrets.SSH_HOST }}
          SSH_USER: ${{ secrets.SSH_USER }}
          SSH_KEY:  ${{ secrets.SSH_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$SSH_KEY" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh -o StrictHostKeyChecking=no $SSH_USER@$SSH_HOST '
            cd /var/www/my-app &&
            git pull &&
            npm ci &&
            npm run build &&
            pm2 reload my-app || pm2 start dist/server.js --name my-app
          '

4) Secure Setup: Using Secrets

The deployment example uses secrets. Register the following in your repository settings:

• SSH_HOST: Server address
• SSH_USER: User for connection
• SSH_KEY: Private key (commonly PEM format) Ensure the private key is never stored in the repository, and that its corresponding public key is recorded on the server.

5) Common Roadblocks for Beginners

1) “Tests Fail Due to Missing Tests”

If npm test runs no actual tests, it will fail. Even if you can't write tests yet, set up a placeholder test script for now.

2) “I Only Want to Run on Develop Branch”

Just change the branch:

on:
  push:
    branches: ["develop"]

3) “Deployment Seems Risky”

Initially, comment out the deployment job and stabilize CI first. Or, use workflow_dispatch to manually trigger deployment.

6) Wrap-Up: Steps to Minimize Failures

1. Start with ci.yml for automated testing.
2. Use npm ci + cache for stable executions.
3. Use needs: test for a test success → deployment flow.
4. Manage sensitive data with secrets. Following these steps, your project will operate more smoothly from the moment you commit. The next steps could include expanding to test matrices (various Node versions), environment-specific deployments (dev/staging/prod), or artifact uploads.