How to Run Cypress in Parallel With Cypress Cloud in GitHub Actions

Cypress Cloud balances specs across identical machines when every job records with the same build id.

Set record: true and parallel: true, pass the CYPRESS_RECORD_KEY secret, and run several matrix machines that share one ci-build-id so Cloud distributes specs among them.

Steps

• Store the record key as the CYPRESS_RECORD_KEY secret.
• Run N identical matrix machines (the values are just placeholders).
• Set record: true and parallel: true on the action.
• Give every machine the same ci-build-id so Cloud groups them.

Workflow

jobs:
  cypress:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        machine: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - uses: cypress-io/github-action@v6
        with:
          start: npm start
          wait-on: 'http://localhost:3000'
          record: true
          parallel: true
          group: 'e2e'
          ci-build-id: ${{ github.run_id }}-${{ github.run_attempt }}
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Gotchas

• Parallelization needs Cypress Cloud; parallel: true without record: true is rejected.
• A mismatched ci-build-id splits machines into separate runs instead of balancing one.

Related guides