GitHub actions with Cypress

This page covers running Replay-recorded Cypress 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 cypress.config.js and the support file yet, start with Record your Cypress tests.

Simple setup

A working setup needs three things:

1. The Replay plugin in cypress.config.js and the support file imported in cypress/support/e2e.js.
2. A workflow that installs the Replay browser before running tests.
3. REPLAY_API_KEY available to the test step.

cypress.config.js

cypress.config.js
 1const { defineConfig } = require('cypress')
 2const { plugin: replayPlugin, wrapOn } = require('@replayio/cypress')
 3
 4module.exports = defineConfig({
 5  e2e: {
 6    setupNodeEvents(cyOn, config) {
 7      const on = wrapOn(cyOn)
 8      replayPlugin(on, config, {
 9        apiKey: process.env.REPLAY_API_KEY,
10        upload: true,
11      })
12      return config
13    },
14  },
15})

Make sure cypress/support/e2e.js imports the Replay support module so Cypress commands appear in the Replay DevTools timeline:

cypress/support/e2e.js
require('@replayio/cypress/support')

.github/workflows/e2e.yml

.github/workflows/e2e.yml
 1name: End-to-end tests
 2on:
 3  pull_request:
 4  push:
 5    branches: [main]
 6jobs:
 7  cypress-run:
 8    runs-on: ubuntu-22.04
 9    steps:
10      - name: Checkout
11        uses: actions/checkout@v4
12      - name: Install Replay Chromium
13        run: npx replayio install
14      - name: Cypress run
15        uses: cypress-io/github-action@v6
16        with:
17          browser: replay-chromium
18        env:
19          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. The cypress-io/github-action step takes care of installing dependencies and Cypress itself, so a separate npm ci step is not required.

Adding Replay to an existing workflow

Replay does not replace your existing test workflow—it only adds the browser install, switches the browser, and wires the API key into the test step.

• Add npx replayio install before tests run. Chromium being preinstalled on the runner does not cover Replay—you still need this step.
• Run with browser: replay-chromium in cypress-io/github-action, or pass --browser replay-chromium if you invoke cypress run directly.
• Pass REPLAY_API_KEY to the step that runs tests via env: (using secrets.REPLAY_API_KEY).
• Confirm setupNodeEvents returns config. Without that return, Cypress will not see the Replay browser registration and the run fails with Browser: Replay Chromium was not found.

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 replayPlugin in cypress.config.js—not in YAML. The plugin 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

cypress.config.js
 1const { defineConfig } = require('cypress')
 2const { plugin: replayPlugin, wrapOn } = require('@replayio/cypress')
 3
 4module.exports = defineConfig({
 5  e2e: {
 6    setupNodeEvents(cyOn, config) {
 7      const on = wrapOn(cyOn)
 8      replayPlugin(on, config, {
 9        apiKey: process.env.REPLAY_API_KEY,
10        upload: {
11          statusThreshold: 'failed',
12        },
13      })
14      return config
15    },
16  },
17})

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

If your workflow still uses the legacy replayio/action-upload GitHub Action, that action accepts a public input. New Cypress setups should rely on replayPlugin 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 uses browser: replay-chromium (or --browser replay-chromium). Look for the [replay.io] log lines at the end of the test step.
• Browser: Replay Chromium was not found — Either setupNodeEvents is not returning config, the support file import is missing, or npx replayio install did not run. See the Cypress troubleshooting guide for the full list of causes.
• 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.
• Browser launches but does not record — On older Ubuntu runners, OpenSSL 1.1 may be missing. See the Cypress troubleshooting guide for the install snippet.