⚙️ GitHub Actions for CI

Why GitHub Actions

Plenty of CI platforms exist — Jenkins, CircleCI, GitLab CI, Travis. GitHub Actions won a huge share of the JavaScript world for one simple reason: it lives inside GitHub. There's no separate service to sign up for, no webhook to wire, no dashboard to babysit. You commit a YAML file to .github/workflows/, and GitHub notices it and runs it. The status shows up directly on your commits and pull requests.

On top of that it has a marketplace of thousands of reusable "actions" — pre-packaged steps like "check out my repo" or "install Node" — so most of a pipeline is assembled from tested building blocks rather than shell scripts you maintain yourself.

The Mental Model

Five words unlock everything: workflow, event, job, step, action. Get these straight and every YAML file reads clearly.

The nesting is strict: a workflow contains jobs, a job contains steps. Jobs run in parallel by default (each on its own runner); steps within a job run in order on the same runner.

Your First Workflow

Create the file .github/workflows/ci.yml. The path matters: GitHub only looks in .github/workflows/. Here's a complete, working CI workflow for a Node.js project, annotated line by line.

name: CI                           # shows up in the Actions tab

on:                                # WHEN to run
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:                              # WHAT to run
  build-and-test:
    runs-on: ubuntu-latest         # a fresh Ubuntu VM for this job
    steps:
      # 1. Clone the repo onto the runner
      - name: Check out code
        uses: actions/checkout@v4

      # 2. Install Node and enable npm caching
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # 3. Install exactly what package-lock.json locks
      - name: Install dependencies
        run: npm ci

      # 4. Cheap checks first
      - name: Lint
        run: npm run lint

      # 5. Then the test suite
      - name: Test
        run: npm test

      # 6. Confirm it builds
      - name: Build
        run: npm run build

The two most important actions here are near-universal:

• actions/checkout@v4 — clones your repository onto the runner. Without it, the runner is an empty machine with no code. It's almost always step one.
• actions/setup-node@v4 — installs a specific Node version and, with cache: 'npm', remembers your downloaded packages between runs so installs are fast.

✓ Check out code            2s
✓ Set up Node.js            4s
✓ Install dependencies     11s
✓ Lint                      3s
✓ Test                     18s
✓ Build                     9s
Build succeeded — a green check appears on your commit

Triggers: the on Block

The on: key decides when a workflow runs. This is where you tune a pipeline to fire on exactly the events you care about.

on:
  # Run when commits land on main
  push:
    branches: [ main ]

  # Run on PRs targeting main — the classic "check before merge"
  pull_request:
    branches: [ main ]

  # Run on a schedule (cron, in UTC): 1:00 AM daily
  schedule:
    - cron: '0 1 * * *'

  # Add a "Run workflow" button in the GitHub UI
  workflow_dispatch:

You can also narrow triggers by path, so a docs-only change doesn't burn a full test run:

on:
  push:
    branches: [ main ]
    paths:
      - 'src/**'
      - 'package.json'
      - 'package-lock.json'
      - '.github/workflows/**'

Matrix Builds

Your library needs to work on Node 18, 20, and 22, on Linux and Windows. Writing six near-identical jobs would be miserable. A matrix generates them for you: define the axes, and GitHub runs every combination in parallel.

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false            # let all combos finish, don't cancel on first fail
      matrix:
        os: [ ubuntu-latest, windows-latest ]
        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

That's 2 operating systems × 3 Node versions = 6 jobs, all from one block. Each runs on its own fresh runner simultaneously, so testing six environments takes about as long as testing one.

Caching & Parallel Jobs

Two levers keep pipelines fast: don't re-download what you already have, and don't run sequentially what could run at once.

Caching

The easiest win is already in your first workflow: cache: 'npm' on setup-node caches your package downloads keyed by package-lock.json. When the lockfile hasn't changed, installs restore from cache in seconds. For finer control you can cache any directory yourself:

- name: Cache npm downloads
  uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

The key is a fingerprint. When the lockfile changes, the hash changes, so you get a fresh cache; otherwise the exact key hits and restores instantly.

Parallel jobs with needs

Split independent work into separate jobs so they run at the same time, then use needs to enforce order only where it truly matters:

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
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npm test

  build:
    needs: [ lint, test ]         # waits for BOTH to pass
    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 build
      - name: Save the build output
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

lint and test run in parallel; build waits for both via needs, then saves its output as an artifact — a file bundle you can download from the run or hand to a later deploy job.

Secrets & Service Containers

Secrets

Pipelines often need a deploy token or an API key — values you must never commit to the repo. Store them in Settings → Secrets and variables → Actions, then read them through the secrets context. GitHub automatically masks them in logs.

- name: Deploy
  run: npm run deploy
  env:
    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
    API_KEY: ${{ secrets.API_KEY }}

Service containers

Integration tests often need a real database. Rather than mocking one, GitHub can spin up a throwaway container alongside your job — a service container. Here's Postgres, ready on localhost:5432 for the length of the job:

jobs:
  integration:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: test_db
        ports:
          - 5432:5432
        # wait until Postgres is actually accepting connections
        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: '20', cache: 'npm' }
      - run: npm ci
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgres://postgres:postgres@localhost:5432/test_db

The options health-check is essential: without it your tests might start before Postgres is ready and fail with confusing connection errors. The --health-cmd makes the job wait until the database actually answers.

Practice & Quiz

name: CI
on:
  push:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Install dependencies
        run: npm ci
      - name: Test
        run: npm test

name: CI
on:
  push:
    branches: [ main ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code          # bug 2: no code on the runner
        uses: actions/checkout@v4
      - name: Set up Node.js          # bug 1: no npm on the runner
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - name: Install dependencies
        run: npm ci
      - name: Test
        run: npm test

jobs:
  test:
    runs-on: ubuntu-latest
    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

Best Practices & Pitfalls

✅ Do

• Use npm ci (not npm install) for fast, reproducible installs from the lockfile
• Pin actions to a major version like @v4 — or a full commit SHA for maximum supply-chain safety
• Enable dependency caching so repeat runs finish in a fraction of the time
• Split lint/test/build into parallel jobs and connect them with needs
• Make the CI check required via branch protection so it actually gates merges

❌ Don't

• Don't hard-code tokens or keys in the YAML — use secrets
• Don't echo secrets or paste them into logs
• Don't reference actions with @master or @latest — an upstream change could silently break or compromise your build
• Don't forget the service-container health check, or tests race the database and fail intermittently

# Good — pinned to a major version, gets patches
- uses: actions/checkout@v4

# Best — pinned to an exact commit, fully reproducible
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11

# Avoid — a moving target you don't control
- uses: actions/checkout@master

Summary

📚 Additional Resources

• GitHub Docs — Quickstart for GitHub Actions
• GitHub Docs — Workflow syntax reference
• GitHub Docs — Using a matrix for your jobs
• GitHub Docs — Using secrets in GitHub Actions

🚀 What's Next?

You can now write a CI workflow that lints, tests, and builds across many environments. Next, Automated Testing Pipelines zooms out to the full test strategy inside a pipeline — running unit, integration, and end-to-end suites together, enforcing coverage gates, and wiring branch protection so nothing ships untested.