cypress-io/github-action

Run Cypress end-to-end and component tests with dependency install and caching handled for you.

Official actionCategory: Testing & CoverageLatest v7View on GitHub

What it does

cypress-io/github-action is the official wrapper for running Cypress in CI. It detects your package manager, installs dependencies, and caches the Cypress binary automatically.

It can also build the app, start a local server, and wait for a URL before running e2e or component tests, which removes most of the boilerplate from Cypress workflows.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
  - uses: cypress-io/github-action@v7
    with:
      build: npm run build
      start: npm start
      wait-on: 'http://localhost:3000'

Inputs

Input	Description	Default	Required
`browser`	Name of the browser to use.	-	No
`start`	Command for starting local server in the background.	-	No
`wait-on`	Local server URL to wait for.	-	No
`build`	Command to run build step before starting tests.	-	No
`spec`	Provide specific specs to run.	-	No
`component`	Run component tests instead of e2e tests.	`false`	No
`record`	Sends test results to Cypress Cloud.	`false`	No
`working-directory`	Working directory containing the Cypress folder.	-	No

Outputs

Output	Description
`resultsUrl`	Cypress Cloud URL if the run was recorded.
`dashboardUrl`	Cypress Cloud URL if the run was recorded (deprecated).

Notes

Do not add your own npm ci step, the action installs dependencies and caches the Cypress binary itself. Set install: false if you really need to manage installs yourself.

Recording to Cypress Cloud needs record: true plus the record key passed as the CYPRESS_RECORD_KEY environment variable, not as an input.

Common errors

The cypress npm package is installed, but the Cypress binary is missing. means a cache restored node_modules without the binary. Let the action manage install/caching, or clear the stale cache.
You passed the --record flag but did not provide us your Record Key. means record: true was set without the CYPRESS_RECORD_KEY env var.
A wait-on timeout (default 60 seconds) means the start command never served the wait-on URL. Check the server logs in the step output and raise wait-on-timeout if the app is just slow to boot.

Security and pinning

Pin the action to a commit SHA and pass CYPRESS_RECORD_KEY from a secret, never inline it in the workflow.
Cypress test code runs with full access to the job token; keep permissions on the job to the minimum (usually contents: read).

Alternatives and related

actions/setup-nodeInstall a specific Node.js version and cache your npm, yarn, or pnpm dependencies. actions/cacheCache any files between workflow runs, keyed on a hash of your lockfiles. dorny/test-reporterTurn test result files (JUnit, TRX, JSON) into a GitHub check run with annotations.

Frequently asked questions

Do I need to run npm install before the Cypress action?

No. The action detects npm/yarn/pnpm, installs dependencies, and caches the Cypress binary. A separate install step is redundant unless you set install: false.

How do I run Cypress tests in parallel?

Set record: true and parallel: true with a shared ci-build-id across a job matrix, and provide CYPRESS_RECORD_KEY. Load balancing requires Cypress Cloud recording.