What You’re Doing

You have a working monorepo with type checking, linting, tests, and build orchestration via Turborepo. But none of this runs automatically when code is pushed. You’re going to build a GitHub Actions workflow that runs the full quality gate on every push and pull request, uses Turborepo for caching, and adds Lighthouse CI performance budgets to catch regressions before they ship.

Why It Matters

A CI pipeline is where architecture decisions become enforceable. The boundary rules you configured in Exercise 6 only matter if they run on every pull request. The TypeScript incremental builds from Exercise 5 only save time if CI caches the .tsbuildinfo files. The Turborepo caching from Exercise 4 only pays off if CI shares a remote cache across runs. Without CI, your architecture is a suggestion. With CI, it’s a gate.

Prerequisites

• Node.js 20+
• pnpm 9+

Setup

You should be continuing from where Exercise 7 (Design System Governance) left off. If you need to catch up:

git checkout 07-cicd-start
pnpm install

Open .github/workflows/ci.yml — it contains a placeholder with the trigger configuration and a TODO comment.

Create the Basic Workflow

Build the workflow file from scratch. Open .github/workflows/ci.yml and add the foundation:

name: CI

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
Note Minimal clone depth for Turborepo change detection without downloading full history.
      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'
Note Caches ~/.pnpm-store across runs so only new packages are downloaded.
      - run: pnpm install --frozen-lockfileNote Fails the build if the lockfile is out of date, preventing dependency drift.

What Each Step Does

• actions/checkout@v4: Clones the repository. fetch-depth: 2 fetches the current commit and its parent, which is enough for Turborepo’s change detection without downloading the entire git history.

• pnpm/action-setup@v4: Installs pnpm globally on the runner. The version: 9 matches the version used in development.

• actions/setup-node@v4: Installs Node.js and caches the pnpm store. The cache: "pnpm" option tells the action to cache ~/.pnpm-store between runs, so subsequent installs only download new or changed packages.

• pnpm install --frozen-lockfile: Installs dependencies from the lockfile exactly as specified. The --frozen-lockfile flag fails the build if the lockfile is out of date — this catches cases where someone added a dependency but forgot to commit the updated lockfile.

Checkpoint

You have a workflow that installs dependencies. It doesn’t run any checks yet, but the foundation is correct.

Add Turborepo-Powered Quality Checks

Add the typecheck, lint, test, and build steps to the build job in .github/workflows/ci.yml. Each one delegates to Turborepo so it benefits from caching and dependency-aware execution:

- name: Typecheck
  run: pnpm turbo typecheck

- name: Lint
  run: pnpm turbo lint

- name: Test
  run: pnpm turbo test

- name: Build
  run: pnpm turbo build

These run sequentially in the build job. Each step uses Turborepo’s local cache, so if the typecheck already built @pulse/shared, the lint step’s cache for that package is warm.

Configure Remote Caching

Turborepo’s local cache lives on the runner’s filesystem and is discarded when the runner shuts down. Remote caching stores build artifacts in a shared cache that persists across CI runs.

Add environment variables for remote caching. Update the build job in .github/workflows/ci.yml:

build:
  runs-on: ubuntu-latest
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
Note These environment variables enable Turborepo remote caching across CI runs.  steps:
    # ... existing steps

The behavior change is significant. Without remote caching, the first CI run after every push rebuilds everything. With remote caching, a CI run that builds @pulse/shared uploads the artifact. The next CI run (on a different pull request that didn’t change @pulse/shared) downloads the cached artifact instead of rebuilding. In a large monorepo, this can cut CI time by 50-80%.

Add Matrix Strategy for Parallel Testing

When test suites grow, running them sequentially becomes a bottleneck. Add a second job to .github/workflows/ci.yml—a matrix strategy that runs each package’s tests in its own parallel job:

test:
  runs-on: ubuntu-latest
  strategy:
    matrix:
      package: [analytics, users, ui, shared]
  steps:
    - uses: actions/checkout@v4
      with:
        fetch-depth: 2
Note Matrix strategy spawns four parallel jobs, one per package.
    - uses: pnpm/action-setup@v4
      with:
        version: 9

    - uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: 'pnpm'

    - run: pnpm install --frozen-lockfile

    - name: Test ${{ matrix.package }}
      run: pnpm turbo test --filter=@pulse/${{ matrix.package }}

This creates four parallel jobs — one for each package in the matrix. Each job installs dependencies and runs tests for only its assigned package.

Add Lighthouse CI Performance Budgets

Performance budgets catch regressions before they ship. Add a third job to .github/workflows/ci.yml—a Lighthouse CI step that builds the dashboard and asserts performance metrics:

lighthouse:
  runs-on: ubuntu-latest
  needs: build
  steps:
Note This job waits for the build job to succeed before running.    - uses: actions/checkout@v4
      with:
        fetch-depth: 2

    - uses: pnpm/action-setup@v4
      with:
        version: 9

    - uses: actions/setup-node@v4
      with:
        node-version: 20
        cache: 'pnpm'

    - run: pnpm install --frozen-lockfile

    - name: Build Dashboard
      run: pnpm turbo build --filter=@pulse/dashboard

    - name: Run Lighthouse CI
      run: |
        npm install -g @lhci/cli
        lhci autorun

Create a lighthouserc.cjs file at the root of the repository:

module.exports = {
  ci: {
    collect: {
      startServerCommand: 'pnpm --filter @pulse/dashboard preview',
      url: ['http://localhost:4173'],
      numberOfRuns: 3,
Note Three runs reduce variance in performance measurements.    },
    assert: {
      assertions: {
        'categories:performance': ['error', { minScore: 0.9 }],
        'largest-contentful-paint': ['error', { maxNumericValue: 2500 }],
        'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }],
        'total-byte-weight': ['error', { maxNumericValue: 200000 }],
Note Each assertion defines a performance budget that fails the CI pipeline if exceeded.      },
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
};

Checkpoint

The Lighthouse CI configuration is valid. The assertions define concrete performance budgets. The lighthouse job depends on the build job completing first (via needs: build).

Review the Complete Workflow

The three jobs form a dependency graph. The build job runs the sequential quality gate. The test job uses a matrix strategy to run each package’s tests in parallel. The lighthouse job depends on build completing first.

flowchart TD
    Push["Push / Pull Request"]

    subgraph Build["build job"]
        direction TB
        Checkout1["Checkout + Install"]
        TC["Typecheck (turbo)"]
        Lint["Lint (turbo)"]
        Test1["Test (turbo)"]
        B["Build (turbo)"]
        Checkout1 --> TC --> Lint --> Test1 --> B
    end

    subgraph TestMatrix["test job (matrix)"]
        direction TB
        T_Analytics["Test @pulse/analytics"]
        T_Users["Test @pulse/users"]
        T_UI["Test @pulse/ui"]
        T_Shared["Test @pulse/shared"]
    end

    subgraph LH["lighthouse job"]
        direction TB
        LH_Build["Build Dashboard"]
        LH_Run["Lighthouse CI Assertions"]
        LH_Build --> LH_Run
    end

    Push --> Build
    Push --> TestMatrix
    Build -->|"needs: build"| LH

The final .github/workflows/ci.yml should have three jobs:

1. build: Installs dependencies, runs typecheck/lint/test/build with Turborepo
2. test: Matrix strategy that runs each package’s tests in parallel
3. lighthouse: Builds the dashboard and asserts performance budgets

You can validate the YAML syntax locally:

npx yaml-lint .github/workflows/ci.yml

Or paste it into GitHub’s workflow editor (Actions tab in the repository) to check for syntax errors.

Checkpoint

The CI workflow YAML is valid. It covers type checking, linting, testing, building, and performance budgets. Turborepo handles caching within each job. Remote caching is configured for cross-run artifact sharing.

Solution

If you need to catch up, the completed state for this exercise is available on the 08-testing-start branch:

git checkout 08-testing-start
pnpm install

Stretch Goals

• PR comment with Lighthouse scores: Add a step that posts the Lighthouse report as a comment on the pull request using marocchino/sticky-pull-request-comment@v2. This gives reviewers performance data inline with the code review.
• Affected-only testing: Replace the matrix strategy with turbo test --filter=...[HEAD^1] to only test packages affected by the current push. This is Turborepo’s change detection — it compares the current commit against the parent and only runs tasks for packages with changed files.
• Deployment step: Add a conditional deployment step that only runs on pushes to main (not pull requests). Deploy the built dashboard to Vercel, Netlify, or a static hosting provider.

What’s Next

You have a CI pipeline that enforces your architecture on every push. But you don’t have tests yet. In the next exercise, you’ll write Playwright E2E tests that exercise the composed application, mock APIs with MSW, and record HAR fixtures for deterministic test replay.