cypress-io/github-action

The cypress-io/github-action is a GitHub Action designed to run Cypress End-to-End or Component tests within GitHub Actions CI workflows. It provides several high-level features to simplify test execution, including:

• Simplified Execution: Single-line calls to install dependencies and run tests.
• App Coordination: Built-in options to build the application, start a server, and wait for a specific URL to be available before running tests.
• Dependency Management: Automatic dependency installation based on npm, pnpm, or Yarn Classic lock files.
• Caching: Caching of the Cypress binary and dependencies (for npm and Yarn Classic) to reduce bandwidth and speed up runs.
• Cypress Cloud Integration: Support for recording test results to Cypress Cloud, including parallel execution.
• Observability: Generation of job summaries for quick access to results and built-in debugging utilities like a ping utility for server reachability.
• Environment Independence: Docker compatibility to ensure stable environments regardless of GitHub-hosted runner changes.

To debug your environment, you can run npx cypress info to print Cypress and OS information, including detected browsers.

If you are not using the build parameter, you can simply pass npx cypress info to the build option.

If you are already using the build parameter for your application, you should split the action into two steps: one for installation (runTests: false) and one for running the info command, followed by the actual test run (install: false).

# Option 1: Using the build parameter directly
- name: Cypress run
  uses: cypress-io/github-action@v7
  with:
    build: npx cypress info

# Option 2: Splitting steps if 'build' is already used for your app
- name: Cypress install
  uses: cypress-io/github-action@v7
  with:
    runTests: false
- name: Cypress info
  run: npx cypress info
- name: Cypress run
  uses: cypress-io/github-action@v7
  with:
    install: false
    # rest of your parameters

When running parallel tests, you can overwrite the ci-build-id used to link separate machines into a single run in Cypress Cloud.

Best Practice: To avoid "Build already finished" errors when re-running a workflow, generate a unique ID in a separate job using a timestamp or UUID, then pass it to the testing jobs.

Example of a robust parallel setup:

jobs:
  prepare:
    outputs:
      uuid: ${{ steps.uuid.outputs.value }}
    steps:
      - name: Generate unique ID 💎
        id: uuid
        run: echo "value=sha-$GITHUB_SHA-time-$(date +\"%s\")" >> $GITHUB_OUTPUT

  smoke-tests:
    needs: ['prepare']
    steps:
      - uses: actions/checkout@v7
      - uses: cypress-io/github-action@v7
        with:
          record: true
          parallel: true
          ci-build-id: ${{ needs.prepare.outputs.uuid }}
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

To load balance tests across multiple machines, use a GitHub Actions strategy: matrix to spawn multiple containers.

Requirements:

• A Cypress Cloud account.
• Set record: true and parallel: true in the action configuration.
• Provide a group name to group the parallel runs.
• Pass CYPRESS_RECORD_KEY and GITHUB_TOKEN in the env section.

Important: Set fail-fast: false in your matrix strategy. If one container fails and kills the job immediately, it can leave Cypress Cloud processes hanging.

Note: The action does not create containers; it uses the GitHub matrix to link containers into a single logical Cypress Cloud run.

name: Parallel Cypress Tests
on: push
jobs:
  test:
    name: Cypress run
    runs-on: ubuntu-24.04
    strategy:
      fail-fast: false
      matrix:
        containers: [1, 2, 3]
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Cypress run
        uses: cypress-io/github-action@v7
        with:
          record: true
          parallel: true
          group: 'Actions example'
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.EXAMPLE_RECORDING_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The action automatically installs local dependencies using lock files. Ensure exactly one lock file is present at the root or in the working directory.

Note on Caching:

• Cypress binary: Cached in $HOME/.cache/Cypress (or CYPRESS_CACHE_FOLDER) with label cypress-<platform-and-architecture>-hash.
• npm: Cached in $HOME/.npm with label npm-<platform-and-architecture>-hash.
• Yarn Classic: Cached in $HOME/.cache/yarn with label npm-<platform-and-architecture>-hash.
• pnpm & Yarn Modern: The action does not include built-in caching for these. Use actions/setup-node to enable caching for these package managers.