ci.yml

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

# Builds the Jekyll site, runs UI regression tests on PRs, and deploys to
# GitHub Pages on pushes to master.
name: Build, test & deploy

on:
  # Runs on pushes targeting the default branch
  push:
    branches: [master]
  pull_request:
    branches:
      - master 

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
# and posting sticky comments on PRs from the ui-regression-tests job.
permissions:
  contents: read
  pages: write
  id-token: write
  pull-requests: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Builds the site with the GitHub Pages base path and uploads the Pages
  # artifact consumed by deploy-pages.
  build-pages:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install webp encoder
        # _plugins/webp_generator.rb shells out to cwebp to write .webp
        # siblings of every PNG/JPEG into the deployed _site. The plugin
        # no-ops gracefully if cwebp is missing, but production should ship
        # the WebP siblings so future <picture> markup can use them.
        run: sudo apt-get update -qq && sudo apt-get install -y -qq webp
      - name: Setup Ruby
        uses: ruby/setup-ruby@086ffb1a2090c870a3f881cc91ea83aa4243d408 # v1.195.0
        with:
          ruby-version: '3.1' # Not needed with a .ruby-version file
          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
          cache-version: 0 # Increment this number if you need to re-download cached gems
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - name: Install npm deps
        run: npm ci
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build site for Pages
        # Outputs to the './_site' directory by default
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production
      - name: Generate Pagefind search index
        # Pagefind crawls the built _site/ and writes /_site/pagefind/* — the
        # static UI bundle + WASM index that the header search input loads.
        run: npx pagefind --site _site
      - name: Upload Pages artifact
        # Automatically uploads an artifact from the './_site' directory by default
        uses: actions/upload-pages-artifact@v3

  # UI regression tests (PRs only). Builds the site without a base path so
  # tested URLs match production paths exactly; independent of build-pages.
  ui-regression-tests:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    # Run inside Playwright's official image — it ships with Node + Chromium +
    # all system deps preinstalled, eliminating the ~5min apt step on the bare
    # runner. IMPORTANT: keep this tag in sync with @playwright/test in
    # package.json. Bump both together.
    container:
      image: mcr.microsoft.com/playwright:v1.59.1-jammy
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      # Playwright's jammy image is slim and ships without:
      #   - libyaml-0-2:    psych.so (YAML parsing) needs it at runtime
      #   - build-essential: native gem extensions (http_parser.rb) need make + gcc
      #   - libssl-dev:     eventmachine native ext needs OpenSSL headers (-lcrypto)
      # Without these, ruby/setup-ruby + bundle install fail.
      - name: Install Ruby runtime + build deps
        run: |
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends \
            libyaml-0-2 \
            build-essential \
            libssl-dev
      - name: Setup Ruby
        uses: ruby/setup-ruby@086ffb1a2090c870a3f881cc91ea83aa4243d408 # v1.195.0
        with:
          ruby-version: '3.1'
          bundler-cache: true
          cache-version: 0
      - name: Build site for tests
        run: bundle exec jekyll build
        env:
          JEKYLL_ENV: production
      - name: Install npm deps
        run: npm ci
      - name: Run UI tests
        id: ui_tests
        run: npm test
        env:
          # GitHub Actions sets $HOME=/github/home (uid 1001), but the
          # Playwright container runs as root — firefox refuses to launch
          # under a $HOME it doesn't own. /root is owned by the running
          # user, satisfies firefox, and chromium/webkit don't care.
          HOME: /root
      - name: Upload Playwright report
        id: upload_report
        if: always() && steps.ui_tests.conclusion != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: |
            playwright-report/
            test-results/
          retention-days: 14
      - name: Generate test summary
        if: always() && steps.ui_tests.conclusion != 'skipped'
        env:
          ARTIFACT_URL: ${{ steps.upload_report.outputs.artifact-url }}
        run: |
          node scripts/ci-test-summary.mjs > /tmp/ui-test-summary.md
          cat /tmp/ui-test-summary.md >> "$GITHUB_STEP_SUMMARY"
      - name: Post UI tests comment on PR
        if: always() && github.event_name == 'pull_request' && steps.ui_tests.conclusion != 'skipped'
        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.0
        with:
          header: ui-tests
          path: /tmp/ui-test-summary.md

  # Lighthouse CI (PRs only). Runs against the freshly-built site and asserts
  # against budgets in lighthouserc.json. Reuses the Playwright container
  # because it already ships Chrome + Node 20+ (lhci 0.15 needs both).
  lighthouse-ci:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.59.1-jammy
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install Ruby runtime + build deps
        run: |
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends \
            libyaml-0-2 \
            build-essential \
            libssl-dev
      - name: Setup Ruby
        uses: ruby/setup-ruby@086ffb1a2090c870a3f881cc91ea83aa4243d408 # v1.195.0
        with:
          ruby-version: '3.1'
          bundler-cache: true
          cache-version: 0
      - name: Build site
        run: bundle exec jekyll build
        env:
          JEKYLL_ENV: production
      - name: Install npm deps
        run: npm ci
      - name: Generate Pagefind search index
        # lhci serves _site/, so the search bundle must exist there or the
        # header search input would 404 on every URL it audits.
        run: npx pagefind --site _site
      - name: Run Lighthouse CI
        id: lhci
        # The Playwright image ships chromium at /ms-playwright/chromium-*/...
        # rather than /usr/bin/google-chrome, so chrome-launcher (used by lhci)
        # can't auto-detect it. Resolve the binary via the playwright Node API
        # and pass it through as CHROME_PATH.
        run: |
          export CHROME_PATH="$(node -e 'console.log(require("playwright").chromium.executablePath())')"
          echo "Using Chrome at: $CHROME_PATH"
          npx lhci autorun --config=lighthouserc.json
        env:
          # Optional — set this secret to post lhci status checks via the
          # Lighthouse CI GitHub App. Without it, lhci runs but skips the
          # status-check post.
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
      - name: Upload Lighthouse reports
        id: upload_lhci
        if: always() && steps.lhci.conclusion != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: lighthouse-reports
          path: .lighthouseci/
          retention-days: 14
      - name: Generate Lighthouse summary
        if: always() && steps.lhci.conclusion != 'skipped'
        env:
          ARTIFACT_URL: ${{ steps.upload_lhci.outputs.artifact-url }}
        run: |
          node scripts/ci-lighthouse-summary.mjs > /tmp/lighthouse-summary.md
          cat /tmp/lighthouse-summary.md >> "$GITHUB_STEP_SUMMARY"
      - name: Post Lighthouse comment on PR
        if: always() && github.event_name == 'pull_request' && steps.lhci.conclusion != 'skipped'
        uses: marocchino/sticky-pull-request-comment@52423e01640425a022ef5fd42c6fb5f633a02728 # v2.9.0
        with:
          header: lighthouse
          path: /tmp/lighthouse-summary.md

  # Publishes the Pages artifact from build-pages. Runs only on master pushes.
  deploy-pages:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    if: github.event_name == 'push'
    needs: build-pages
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4