26CI/CD with GitHub Actions

26.1 The four-part pipeline shape

26.2 Minimal Playwright pipeline

name: e2e

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

This is what most teams ship with. Now let's make it production-grade.

26.3 Production-grade pipeline with sharding

name: e2e
on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 6 * * *'        # nightly smoke
  workflow_dispatch:           # manual trigger

concurrency:
  group: e2e-${{ github.ref }}
  cancel-in-progress: true     # latest commit cancels older runs on same branch

jobs:
  test:
    timeout-minutes: 60
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false         # one shard failing does NOT cancel the others
      matrix:
        shard: [1/4, 2/4, 3/4, 4/4]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20.11.1'   # pin exact version, not "20"
          cache: 'npm'

      - name: Install npm deps
        run: npm ci                  # deterministic; respects package-lock.json

      - name: Cache Playwright browsers
        uses: actions/cache@v4
        id: pw-cache
        with:
          path: ~/.cache/ms-playwright
          key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}

      - name: Install Playwright browsers
        if: steps.pw-cache.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps

      - name: Install browser system deps (always)
        if: steps.pw-cache.outputs.cache-hit == 'true'
        run: npx playwright install-deps

      - name: Run tests (shard ${{ matrix.shard }})
        run: npx playwright test --shard=${{ matrix.shard }}
        env:
          BASE_URL: ${{ secrets.STAGING_URL }}
          CI: 'true'

      - name: Upload blob report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: blob-report-${{ strategy.job-index }}
          path: blob-report
          retention-days: 7

      - name: Upload traces
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: traces-${{ strategy.job-index }}
          path: test-results/
          retention-days: 7

  merge-reports:
    if: always()
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20.11.1', cache: 'npm' }
      - run: npm ci
      - uses: actions/download-artifact@v4
        with:
          path: all-blob-reports
          pattern: blob-report-*
          merge-multiple: true
      - run: npx playwright merge-reports --reporter=html ./all-blob-reports
      - uses: actions/upload-artifact@v4
        with:
          name: merged-html-report
          path: playwright-report
          retention-days: 14

26.4 Walking through every important line

Triggers

• push on main — runs on every merge
• pull_request — runs on every PR
• schedule with cron — nightly smoke for catching infra drift
• workflow_dispatch — manual "Run workflow" button in the UI

concurrency — cancel older runs

When you push twice quickly to the same branch, the first run is still chewing through tests when the second starts. cancel-in-progress: true kills the older one — saves CI minutes and gives you faster feedback on the latest commit.

fail-fast: false

By default GitHub Actions cancels the whole matrix the moment one job fails. For test suites that's wrong — you want to see all shard failures, not just the first one. fail-fast: false lets every shard run to completion.

Sharding with matrix

--shard=1/4 tells Playwright "run a quarter of the tests, you are shard 1 of 4". The matrix runs four parallel jobs, each on its own runner. A 30-minute suite becomes a 7.5-minute suite.

Pin the Node version

node-version: '20' picks "latest 20" and can change overnight; '20.11.1' is reproducible. Floating Node versions cause "passed yesterday, fails today" mysteries.

npm ci vs npm install

Caching

• cache: 'npm' on setup-node — caches ~/.npm by hashing package-lock.json. Saves 30–60s.
• Separate cache for ~/.cache/ms-playwright (browser binaries) — saves 1–2 minutes.
• install-deps still runs after a cache hit to install OS libraries (libnss, libgtk, etc.) — Playwright browsers won't launch without them.

if: always(), if: failure(), if: success()

• if: always() — run even if a previous step failed. Use for uploading reports/traces — you most need them when the test step failed.
• if: failure() — only on failure. Use for things you only care about when something broke.
• if: success() — default; only when previous steps passed.

blob reports + merge-reports

Each shard emits a "blob" report (binary intermediate). The merge-reports job downloads all of them and merges into a single HTML report — so you have one URL to look at, not four.

26.5 Retries strategy

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: { trace: 'on-first-retry' },
});

• Local: 0 retries. A flake locally is a real bug. Fix it before pushing.
• CI: 2 retries. Absorbs occasional infra noise. But trace is captured on the first retry — so you can investigate even if it ultimately passes.
• Trace on first retry, not every run. Cheap when tests pass, full trace when they don't.

26.6 Monitoring retry rates

Retries hide failures. If a test needs 2 retries to pass, it is flaky — just less visibly. Two practices:

1. Add a report that lists tests that needed any retry to pass (parse the JSON report or use a tool like Currents.dev / Sorry Cypress / a custom dashboard).
2. Set a threshold: if retry rate > 2% across a week, halt new feature merges until top flakes are fixed or quarantined.

26.7 Quarantining flaky tests

// Tag and isolate
test('checkout flow @quarantine', async ({ page }) => { /* ... */ });

// Run normally without quarantined
// npx playwright test --grep-invert "@quarantine"

// Nightly job runs ONLY quarantined to track if they've recovered
// npx playwright test --grep "@quarantine"

26.8 Debugging remote failures with show-trace

Test fails on CI, passes locally. Workflow:

1. Open the failing GitHub Actions run.
2. Scroll to the artifacts section; download traces-* or the merged report.
3. Unzip; find the trace.zip inside (one per failure).
4. Locally: npx playwright show-trace path/to/trace.zip
5. Scrub the timeline. Inspect the DOM at the failure step. Look at network. The cause is usually obvious in 30 seconds.

26.9 Other CI niceties

# Secrets — never hardcode credentials
env:
  ADMIN_PASS: ${{ secrets.ADMIN_PASS }}
  DB_URL:    ${{ secrets.DB_URL }}

# Allow a step to fail without failing the whole job
- run: npx playwright test --grep "@experimental"
  continue-on-error: true

# Custom name in the UI per shard
- name: "Tests · shard ${{ matrix.shard }}"
  run: npx playwright test --shard=${{ matrix.shard }}

26.10 The 3-line summary you can quote in an interview