How to Run Cypress Tests in CI on GitHub Actions

The official cypress-io/github-action wraps install, caching, server startup, and the test run behind a single step.

Use cypress-io/github-action with start to boot your app and wait-on to hold until it responds, so the browser tests run against a live server.

Steps

• Check out the repo and set up Node.
• Use cypress-io/github-action with start: npm start.
• Set wait-on to your app URL so tests wait for readiness.
• Upload screenshots and videos on failure.

Workflow

jobs:
  cypress:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - uses: cypress-io/github-action@v6
        with:
          start: npm start
          wait-on: 'http://localhost:3000'
          wait-on-timeout: 120
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: cypress-artifacts
          path: |
            cypress/screenshots
            cypress/videos

Gotchas

• The action caches the Cypress binary automatically; do not also cache ~/.cache/Cypress by hand or you double the work.
• On Linux the action runs under xvfb for you, so no manual virtual display setup is needed.

Related guides