Setting Up Automated Testing and Deployment for Node.js Projects with GitHub Actions for Beginners

Ever wondered why something works locally but breaks on the server? Manual tests and uploads can lead to inevitable mistakes. Today, let’s simplify your work by setting up an automated testing and deployment flow for Node.js projects using GitHub Actions. Once configured, your code push will automatically lead to testing and deployment.

Checklist for Getting Started

• GitHub Repository
• Node.js Project (e.g., Express)
• Test scripts in package.json (create if needed)
• Deployment target (e.g., Linux server or artifact upload)

Example Project Script (Minimal Setup)

{
  "scripts": {
    "test": "node -e \"console.log('test ok')\"",
    "build": "node -e \"console.log('build ok')\""
  }
}

If you don’t have tests yet, start with a placeholder like above, and expand with tools like Jest later.

Understanding GitHub Actions Basics

GitHub Actions runs by reading YAML files from your repository’s .github/workflows/ directory.

• on: Specifies when to run (e.g., push or pull request)
• jobs: Defines the tasks to perform
• steps: Outlines task steps (checkout, install, test, etc.)

Step 1: Create a Continuous Integration (CI) Workflow

Create the file: .github/workflows/ci.yml

name: CI

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

jobs:
  test:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        node-version: [18, 20]

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

      - name: Setup 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

Common Beginner Roadblocks

• Use npm ci instead of npm install for more stable installs based on package-lock.json.
• Run on pull_request to catch issues early.
• Use multiple Node versions to avoid version-specific issues.

Step 2: Connect to Continuous Deployment (CD)

Deployment environments vary. We’ll illustrate deploying to a server via SSH—common and straightforward.

Example Server Deployment Flow

1. Push to main branch
2. Pass tests
3. Connect to server
4. Update code + install + build + restart Create the file: .github/workflows/cd.yml

name: CD

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"

      - name: Install Dependencies
        run: npm ci

      - name: Run Tests
        run: npm test

      - name: Build (if needed)
        run: npm run build --if-present

      - name: Deploy to Server (SSH)
        
             
             
             
         

Setting Secrets (Critical)

In your repository settings, register the following as Secrets:

• DEPLOY_HOST: Server address
• DEPLOY_USER: Login username
• DEPLOY_SSH_KEY: Private Key Never hardcode the private key. Always use Secrets for security.

Pro Tips: Troubleshooting Common Issues

1) “Failed to Install Dependencies”

• Ensure package-lock.json is up-to-date.
• Check Node version compatibility (local vs. CI).

2) “Missing pm2 Command on Server”

• Install pm2 on the server: npm i -g pm2
• Or adapt the restart command to your preferred system (e.g., systemd).

3) “Permission/Path Issues”

• Check permissions for the deployment folder (/var/www/myapp).
• Ensure the account can perform git pull.

Conclusion: Make Deployment a Habit

As a beginner, deploying even small features can feel overwhelming. By automating tests and deployments with GitHub Actions, your workflow becomes cleaner, and mistakes are minimized. While we started with SSH deployment, you can expand to artifact uploads, container deployments, and more.

Next, try integrating tools like Jest for testing, separating environment variables, and minimizing user/permissions for deployments.