GitHub Actions
Complete Handbook

name: CI Build                 # Display name in GitHub UI

on:                               # Trigger definition
  push:
    branches: [main, develop]
    paths-ignore: ['**.md']      # skip if only docs changed
  pull_request:
    branches: [main]

concurrency:                      # Cancel redundant runs
  group: ci-${{ github.ref }}
  cancel-in-progress: true

permissions:                      # Least-privilege GITHUB_TOKEN
  contents: read
  pull-requests: write

env:                              # Workflow-level env vars
  NODE_VERSION: '22'

jobs:
  build:
    name: Build & Test
    runs-on: ubuntu-latest       # Runner label
    timeout-minutes: 15          # Fail-safe timeout

    outputs:                      # Pass data between jobs
      version: ${{ steps.ver.outputs.version }}

    steps:
      - name: Checkout
        uses: actions/checkout@v6  # Pin major version

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'             # Built-in dep caching

      - name: Install
        run: npm ci

      - name: Get version
        id: ver
        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm test

      - name: Upload coverage
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: coverage-${{ github.sha }}
          path: coverage/
          retention-days: 14

# Conditional step — only on main
if: github.ref == 'refs/heads/main'

# Always run (even if job failed)
if: always()

# Run on failure only
if: failure()

# Check if PR is from Dependabot
if: github.actor == 'dependabot[bot]'

# Ternary-style using fromJSON
env:
  TARGET: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

# Write to GITHUB_OUTPUT (step outputs)
run: echo "tag=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT

# Write to GITHUB_STEP_SUMMARY (shows in UI)
run: echo "## Build passed ✅" >> $GITHUB_STEP_SUMMARY

# Mask a value in logs
run: echo "::add-mask::$SECRET_VALUE"

# Add a warning annotation
run: echo "::warning file=src/main.ts,line=42::Deprecated API"

- uses: actions/checkout@v6
  with:
    ref: ${{ github.event.pull_request.head.sha }}  # pin PR SHA
    fetch-depth: 0          # full history (needed for git log, SemVer)
    sparse-checkout: |      # only checkout specific dirs
      src/
      tests/
    token: ${{ secrets.MY_PAT }}    # for private repo or push-back
    submodules: recursive  # init all submodules
    lfs: true               # checkout Git LFS files

# Upload — v4 default is zipped
- uses: actions/upload-artifact@v4
  with:
    name: build-${{ github.sha }}
    path: |
      dist/
      !dist/**/*.map          # exclude source maps
    retention-days: 30
    if-no-files-found: error # fail if no files match
    compression-level: 0     # 0 = no zip (Feb 2026 feature)

# Download — pattern matches multiple artifacts from matrix
- uses: actions/download-artifact@v4
  with:
    pattern: build-*          # glob across all named artifacts
    path: all-builds/
    merge-multiple: true    # merge into single dir

jobs:
  test:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: ['20', '22']
        include:                    # Add extra matrix cells
          - os: ubuntu-latest
            node: '22'
            coverage: true
        exclude:                    # Remove specific combinations
          - os: windows-latest
            node: '20'
      fail-fast: false            # Don't cancel all on first failure
      max-parallel: 4             # Limit concurrent jobs

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm ci && npm test
      - name: Coverage
        if: matrix.coverage       # only for specific matrix cell
        run: npm run coverage
      - uses: actions/upload-artifact@v4
        with:
          name: results-${{ matrix.os }}-node${{ matrix.node }}
          path: test-results/

# Cancel in-progress runs for the same branch
concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps: [...]

  test:
    needs: lint               # runs after lint
    runs-on: ubuntu-latest
    steps: [...]

  build:
    needs: test
    runs-on: ubuntu-latest
    outputs:
      image-tag: ${{ steps.tag.outputs.tag }}
    steps: [...]

  deploy-staging:
    needs: build
    environment: staging       # triggers protection rules / approvals
    runs-on: ubuntu-latest
    steps: [...]

  deploy-prod:
    needs: [build, deploy-staging]
    environment: production
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps: [...]

name: Node.js CI

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

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: npm }
      - run: npm ci --prefer-offline
      - run: npm run lint
      - run: npm run type-check

  test:
    needs: lint
    strategy:
      matrix:
        node: ['20', '22']
      fail-fast: false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v4
        with: { node-version: '${{ matrix.node }}', cache: npm }
      - run: npm ci --prefer-offline
      - run: npm test -- --coverage
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-node-${{ matrix.node }}
          path: coverage/
          retention-days: 7