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 6 left off. If you need to catch up:

git checkout 06-cicd-start
pnpm install

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

Step 1: 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

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

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

      - run: pnpm install --frozen-lockfile

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.

Step 2: Add Turborepo-Powered Quality Checks

Add the typecheck, lint, test, and build steps. 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.

Step 3: 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.

1. Add environment variables for remote caching. Update the build job:

build:
  runs-on: ubuntu-latest
  env:
    TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
    TURBO_TEAM: ${{ vars.TURBO_TEAM }}
  steps:
    # ... existing steps

2. 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%.

Step 4: Add Matrix Strategy for Parallel Testing

When test suites grow, running them sequentially becomes a bottleneck. A matrix strategy 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

    - 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.

Step 5: Add Lighthouse CI Performance Budgets

Performance budgets catch regressions before they ship. Add a Lighthouse CI step that builds the dashboard and asserts performance metrics:

lighthouse:
  runs-on: ubuntu-latest
  needs: build
  steps:
    - 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,
    },
    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 }],
      },
    },
    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).

Step 6: Review the Complete Workflow

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.

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.

Solution

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

git checkout 07-testing-start
pnpm install

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.