GitHub Actions CI/CD Tutorial: Workflows, Jobs, and Real-World Pipelines

# io.thecodeforge — GitHub Actions CI Pipeline
#
# This workflow runs on every push to any branch and on every pull request targeting main.
# It has two jobs: one for testing, one for linting — they run in parallel to save time.

name: CI Pipeline

on:
  push:
    branches:
      - '**'          # Trigger on every branch push
  pull_request:
    branches:
      - main          # Extra scrutiny on PRs targeting main

jobs:

  # ── JOB 1: Run the test suite ───────────────────────────────────────────────
  run-tests:
    name: Run Unit & Integration Tests
    runs-on: ubuntu-latest   # GitHub-hosted runner — fresh VM every time

    steps:
      - name: Check out repository code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # SHA-pinned for security

      - name: Set up Node.js 20
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # SHA-pinned
        with:
          node-version: '20'
          cache: 'npm'              # Caches node_modules between runs — huge speed win

      - name: Install dependencies
        run: npm ci                 # 'ci' is stricter than 'install' — uses package-lock.json exactly

      - name: Run tests with coverage
        run: npm test -- --coverage
        env:
          NODE_ENV: test            # Set environment variables inline per step

  # ── JOB 2: Lint the codebase (runs in PARALLEL with run-tests) ───────────────
  lint-code:
    name: ESLint Code Quality Check
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # SHA-pinned

      - name: Set up Node.js 20
        uses: actions/setup-node@4942d1e84afbd3f7d6820020  # SHA-pinned
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint           # Fails the job (and blocks the PR) if lint errors exist

# io.thecodeforge — GitHub Actions Deploy Pipeline
#
# This workflow deploys to staging on every merge to main,
# then requires a manual approval before deploying to production.
# Secrets are scoped per environment so prod credentials are never
# exposed during a staging deploy.

name: Deploy Pipeline

on:
  push:
    branches:
      - main   # Only deploys on merges to main — not on feature branches

jobs:

  # ── JOB 1: Tests must pass before anything deploys ──────────────────────────
  run-tests:
    name: Test Gate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test

  # ── JOB 2: Deploy to Staging (runs after tests pass) ────────────────────────
  deploy-staging:
    name: Deploy to Staging
    runs-on: ubuntu-latest
    needs: run-tests          # Will not start until run-tests job succeeds
    environment: staging      # Unlocks staging environment secrets + protection rules

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Build production bundle
        run: npm run build
        env:
          VITE_API_URL: ${{ vars.API_URL }}   # 'vars' = non-secret config variables (visible in logs)

      - name: Deploy to staging server via SSH
        run: |
          # Write the SSH private key from secrets to a temp file
          echo "${{ secrets.STAGING_SSH_PRIVATE_KEY }}" > /tmp/deploy_key
          chmod 600 /tmp/deploy_key

          # Sync build output to the staging server
          rsync -avz --delete \
            -e "ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no" \
            ./dist/ \
            ${{ secrets.STAGING_USER }}@${{ secrets.STAGING_HOST }}:/var/www/app/

          # Clean up the key file immediately after use
          rm /tmp/deploy_key
        # secrets.STAGING_SSH_PRIVATE_KEY is ONLY available because environment: staging is set above

  # ── JOB 3: Deploy to Production (requires a human to approve in GitHub UI) ──
  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: deploy-staging     # Staging must succeed before prod is even offered
    environment: production   # 'production' environment has required reviewers set in GitHub settings
                              # The workflow PAUSES here until a reviewer approves in the GitHub UI

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Build production bundle
        run: npm run build
        env:
          VITE_API_URL: ${{ vars.API_URL }}

      - name: Deploy to production server via SSH
        run: |
          echo "${{ secrets.PROD_SSH_PRIVATE_KEY }}" > /tmp/deploy_key
          chmod 600 /tmp/deploy_key

          rsync -avz --delete \
            -e "ssh -i /tmp/deploy_key -o StrictHostKeyChecking=no" \
            ./dist/ \
            ${{ secrets.PROD_USER }}@${{ secrets.PROD_HOST }}:/var/www/app/

          rm /tmp/deploy_key

# io.thecodeforge — GitHub Actions Matrix and Cache
#
# This workflow demonstrates a build matrix — running tests across multiple
# Node.js versions and OS combinations simultaneously.
# It also shows manual cache control for fine-grained cache invalidation.

name: Cross-Platform Test Matrix

on:
  pull_request:
    branches:
      - main

jobs:

  test-matrix:
    name: "Node ${{ matrix.node-version }} / ${{ matrix.os }}"
    # ↑ GitHub uses this as the job label in the UI — makes failures obvious at a glance

    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]     # Run on both Linux and Windows
        node-version: ['18', '20']              # And on both Node 18 and 20
        # This creates 2 × 2 = 4 parallel jobs automatically

      fail-fast: false
      # ↑ IMPORTANT: Without this, if Node 18/Linux fails, GitHub cancels
      # the other 3 jobs immediately. Set fail-fast: false to see ALL results.

    runs-on: ${{ matrix.os }}   # Each job uses the OS from its matrix slot

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

      - name: Set up Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
        with:
          node-version: ${{ matrix.node-version }}
          # We're NOT using the built-in cache here — we'll manage it manually
          # to show you exactly what's happening under the hood

      - name: Cache node_modules
        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9  # SHA-pinned
        with:
          path: node_modules
          # Cache key = OS + Node version + hash of package-lock.json
          # If ANY of those change, the cache is invalidated and rebuilt
          key: ${{ runner.os }}-node-${{ matrix.node-version }}-${{ hashFiles('package-lock.json') }}
          # Fallback: if exact key not found, try a key from the same OS+version
          # This restores a slightly stale cache and npm ci tops it up — faster than a cold install
          restore-keys: |
            ${{ runner.os }}-node-${{ matrix.node-version }}-

      - name: Install dependencies
        run: npm ci
        # If the cache hit was exact, npm ci verifies integrity and exits fast (~3s)
        # If partial or no cache, it downloads and the cache is saved after the job

      - name: Run tests
        run: npm test

  # ── Reusable Workflow Call — deploy using a shared template ─────────────────
  # Instead of writing the deploy steps here, we call a workflow defined
  # in a central devops repo. All 12 microservices call this same template.
  deploy-via-shared-template:
    name: Deploy (Shared Workflow)
    needs: test-matrix
    uses: your-org/devops-workflows/.github/workflows/ssh-deploy.yml@main
    # ↑ References a reusable workflow in another repo — pinned to main branch
    with:
      environment: staging
      app-name: 'user-service'
    secrets: inherit
    # ↑ 'inherit' passes all secrets from the calling workflow to the reusable one
    # Without this, the reusable workflow has no access to any secrets