GitHub actions

This page covers running Replay-recorded Playwright tests on GitHub Actions: a minimal workflow, how to add Replay to an existing workflow, and how to control which recordings upload.

If you have not configured playwright.config.ts yet, start with Record your Playwright tests.

Simple setup

A working setup needs three things:

1. The Replay reporter and replay-chromium project in playwright.config.ts.
2. A workflow that installs the Replay browser before running tests.
3. REPLAY_API_KEY available to the test step.

playwright.config.ts

playwright.config.ts
 1import { PlaywrightTestConfig } from "@playwright/test";
 2import { devices as replayDevices, replayReporter } from "@replayio/playwright";
 3
 4const config: PlaywrightTestConfig = {
 5  reporter: [
 6    replayReporter({
 7      apiKey: process.env.REPLAY_API_KEY,
 8      upload: true,
 9    }),
10    ["line"],
11  ],
12  projects: [
13    {
14      name: "replay-chromium",
15      use: { ...replayDevices["Replay Chromium"] },
16    },
17  ],
18};
19export default config;

.github/workflows/e2e.yml

.github/workflows/e2e.yml
 1name: End-to-end tests
 2on:
 3  pull_request:
 4  push:
 5    branches: [main]
 6jobs:
 7  e2e-tests:
 8    runs-on: ubuntu-22.04
 9    steps:
10      - name: Checkout
11        uses: actions/checkout@v4
12      # If you're using Yarn or PNPM, use the appropriate install command here
13      - name: Install dependencies
14        run: npm ci
15      - name: Install Replay Chromium
16        run: npx replayio install
17      - name: Run Playwright tests
18        run: npx playwright test --project replay-chromium
19        env:
20          REPLAY_API_KEY: ${{ secrets.REPLAY_API_KEY }}

Add the workspace API key to Settings → Secrets and variables → Actions as REPLAY_API_KEY so the job can upload to your workspace.

Adding Replay to an existing workflow

Replay does not replace your existing test workflow—it only adds two things and wires the API key into the test step.

• Add npx replayio install before tests run. If you previously installed Playwright's browsers (npx playwright install), keep that step only if you also run non-Replay projects; otherwise the Replay browser is enough. Chromium being preinstalled on the runner does not cover Replay—you still need this step.
• Pass REPLAY_API_KEY to the step that runs tests via env: (using secrets.REPLAY_API_KEY).
• Run with --project replay-chromium if your config defines more than one project. Without --project, Playwright runs all of them.

Leave the rest alone: checkout, dependency install, database setup, preview-deployment waits, etc. are application concerns and stay as-is.

Controlling which recordings upload

Upload behavior is configured on replayReporter in playwright.config.ts—not in YAML. The reporter handles uploads during the test run, so you do not need a separate "upload" step.

For full coverage of upload options, see Upload strategies. The most common patterns are below.

Upload only failed tests

playwright.config.ts
 1import { PlaywrightTestConfig } from "@playwright/test";
 2import { devices as replayDevices, replayReporter } from "@replayio/playwright";
 3
 4const config: PlaywrightTestConfig = {
 5  reporter: [
 6    replayReporter({
 7      apiKey: process.env.REPLAY_API_KEY,
 8      upload: {
 9        statusThreshold: "failed",
10      },
11    }),
12    ["line"],
13  ],
14  projects: [
15    {
16      name: "replay-chromium",
17      use: { ...replayDevices["Replay Chromium"] },
18    },
19  ],
20};
21export default config;

The workflow YAML stays identical to Simple setup above.

Setting recording visibility

Uploaded recordings are private by default. Visibility is managed in the Replay app at the recording or workspace level after upload—it is not a replayReporter option.

If your workflow still uses the legacy replayio/action-upload GitHub Action, that action accepts a public input. New Playwright setups should rely on replayReporter for uploads instead.

Troubleshooting CI runs

• Tests run but no recordings appear — Confirm REPLAY_API_KEY is set in the test step's env, and that the Run Playwright tests step uses --project replay-chromium. Look for the [replay.io] log lines at the end of the test step.
• Workflow logs show "None of the configured projects ran using Replay Chromium" — The CLI did not target the Replay project. Add or fix --project replay-chromium.
• npx replayio install fails — Re-run with verbose logging, and confirm the runner has network access to download the Replay browser.
• Recordings only appear from your local machine — Double-check that the secret is named REPLAY_API_KEY (case-sensitive) and that secrets.REPLAY_API_KEY is referenced correctly in the workflow.