How to Integrate Cypress with Continuous Integration Tools?

To integrate Cypress with continuous integration tools, install your dependencies with npm ci, cache the Cypress binary, and run npx cypress run in headless mode from your CI configuration file. Each provider has its own config: a workflow file for GitHub Actions, .gitlab-ci.yml for GitLab CI, a Jenkinsfile for Jenkins, and config.yml for CircleCI. Cypress runs out of the box on most CI runners, ships official Docker images so you skip OS setup, and supports parallel runs and test recording through Cypress Cloud. The sections below give copy-paste examples for each of the four major tools.

Prerequisites for Running Cypress in CI

Before wiring Cypress into a pipeline, make sure a few things are in place so builds are fast and reproducible.

• Cypress as a dev dependency: Cypress should be in your package.json (install with npm install cypress --save-dev) and committed alongside a lockfile, so CI installs an exact, repeatable version.
• A test script: add a script such as "cypress:run": "cypress run" in package.json so the same command works locally and in CI.
• A reachable application: CI must be able to reach the app under test. Start the server in the job, or point Cypress at a deployed URL with the CYPRESS_BASE_URL environment variable.
• Linux system libraries: a bare Linux runner needs extra OS packages to launch a browser. The official Cypress Docker images include them, so they are the easiest way to avoid missing-dependency errors.

Core Steps to Integrate Cypress into a CI Pipeline

Regardless of which CI tool you use, the underlying flow is the same. Follow these steps:

• Check out your repository in the CI job.
• Install dependencies with npm ci for a clean, lockfile-based install.
• Cache the Cypress binary directory so it is not downloaded on every build.
• Boot or wait for the application under test (use start-server-and-test or wait-on).
• Run the tests headless with npx cypress run, optionally choosing a browser with --browser chrome.
• Collect artifacts (screenshots and videos) and fail the build if any spec fails.

A minimal cache-and-run sequence on a Linux runner looks like this:

# clean install from package-lock.json
npm ci

# cache these paths between builds (key on package-lock.json):
#   ~/.cache/Cypress   <- the Cypress binary
#   ~/.npm             <- the npm cache
# do NOT cache node_modules

# run all specs headless
npx cypress run --browser chrome

Integrate Cypress with GitHub Actions

The simplest path on GitHub is the official cypress-io/github-action. It installs dependencies, caches the Cypress binary, and runs your tests in a single step. Create the file .github/workflows/cypress.yml:

name: Cypress Tests
on: [push, pull_request]
jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cypress-io/github-action@v7
        with:
          browser: chrome
          start: npm start
          wait-on: 'http://localhost:3000'

The action auto-detects your lockfile and caches the binary by default. The start and wait-on inputs boot your app and wait until it responds before the specs run. For a monorepo, point the action at a subfolder with working-directory.

Integrate Cypress with GitLab CI

GitLab CI reads .gitlab-ci.yml from the repo root. Running on the official cypress/included image means the browsers and OS libraries are already present, so the job just installs project dependencies and runs the suite.

stages:
  - test
cypress-e2e:
  stage: test
  image: cypress/included:14.0.0
  script:
    - npm ci
    - npx cypress run --browser chrome
  artifacts:
    when: always
    paths:
      - cypress/screenshots
      - cypress/videos

The artifacts block preserves failure screenshots and run videos even when the job fails, so you can inspect what went wrong from the GitLab UI.

Integrate Cypress with Jenkins

In Jenkins, define a declarative pipeline in a Jenkinsfile. Using the cypress/included Docker image as the agent keeps the agent setup minimal and consistent across builds.

pipeline {
  agent { docker { image 'cypress/included:14.0.0' } }
  stages {
    stage('E2E') {
      steps {
        sh 'npm ci'
        sh 'npx cypress run --browser chrome'
      }
    }
  }
  post {
    always {
      archiveArtifacts artifacts: 'cypress/screenshots/**, cypress/videos/**', allowEmptyArchive: true
    }
  }
}

The post block runs after every build and archives the Cypress artifacts so test evidence is attached to each Jenkins run.

Integrate Cypress with CircleCI

CircleCI reads .circleci/config.yml. As with GitLab and Jenkins, running inside the cypress/included image removes the need to install browsers and system libraries.

version: 2.1
jobs:
  cypress:
    docker:
      - image: cypress/included:14.0.0
    steps:
      - checkout
      - run: npm ci
      - run: npx cypress run
workflows:
  build-and-test:
    jobs:
      - cypress

Run Cypress in Docker

Cypress publishes three official Docker images. cypress/base ships Node.js and the OS libraries, cypress/browsers adds Chrome, Firefox, and Edge, and cypress/included additionally bundles a pinned Cypress version and a ready entrypoint. The included image is the quickest way to get a consistent run anywhere:

# run the project's tests inside the official image
docker run -it -v $PWD:/e2e -w /e2e cypress/included:14.0.0 --browser chrome

Pinning the image tag (for example 14.0.0) keeps the Cypress version locked across local, CI, and Docker runs, which removes a common source of flaky, version-drift failures.

Parallelization and Recording with Cypress Cloud

As a suite grows, a single machine becomes the bottleneck. Cypress Cloud lets you split specs across several CI machines and load-balance them automatically. Add a projectId to your config, store the record key as a CI secret, and run:

npx cypress run --record --parallel --key $CYPRESS_RECORD_KEY

Provision several identical jobs (a build matrix or parallel containers) and Cypress Cloud distributes the specs across them. With the official GitHub Action, the same idea is expressed declaratively:

jobs:
  cypress-run:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        containers: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - uses: cypress-io/github-action@v7
        with:
          record: true
          parallel: true
          group: 'Actions example'
        env:
          CYPRESS_PROJECT_ID: ${{ secrets.CYPRESS_PROJECT_ID }}
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Always read the record key from a secret. Never hardcode CYPRESS_RECORD_KEY or CYPRESS_PROJECT_ID in a file that is committed to the repository.

CI Tools at a Glance

Cross-Browser Testing on a Cloud Grid

Locally and on a default runner, cypress run --browser is limited to the browsers installed on that machine. To validate across many browser and operating system combinations in parallel, point your CI pipeline at a cloud grid. With TestMu AI (Formerly LambdaTest)'s Cypress E2e Testing, the same cypress run command can execute across a large matrix of browsers and OS versions concurrently, so a CI build gets true cross-browser coverage without you maintaining browser binaries on the runners.

Best Practices

• Always run headless: use cypress run, never cypress open, in CI. The open command launches the interactive runner and will hang a pipeline.
• Cache the binary, not node_modules: cache ~/.cache/Cypress and the package manager cache keyed on the lockfile, and install with npm ci for reproducibility.
• Pin versions: pin both the Cypress dependency and the Docker image tag so local, CI, and Docker runs stay in lockstep and avoid version-drift flakiness.
• Keep secrets out of config: read CYPRESS_RECORD_KEY, CYPRESS_PROJECT_ID, and any credentials from CI secrets, never from committed files.
• Always archive artifacts: upload screenshots and videos on every run, including failures, so you can debug without re-running the pipeline.

Frequently Asked Questions

Which command runs Cypress in a CI pipeline?

Use npx cypress run. It executes your specs in headless mode by default, which is what CI requires. The cypress open command is interactive only and should never be used in a pipeline.

Do I need the official Cypress GitHub Action?

It is the simplest option for GitHub Actions. cypress-io/github-action@v7 installs dependencies, caches the Cypress binary, and runs your tests in one step. You can also run npx cypress run manually if you prefer full control over the workflow.

How do I avoid re-downloading the Cypress binary on every build?

Cache the ~/.cache/Cypress directory and your package manager cache between builds, keyed on package-lock.json, and install with npm ci. Do not cache node_modules; cache the binary and the package manager cache instead.

Why use the Cypress Docker images in CI?

On a bare Linux runner, Cypress needs several system libraries to launch a browser. The official cypress/included image ships Node.js, Cypress, and browsers preinstalled, so you skip the OS dependency setup. cypress/base and cypress/browsers are lighter variants for custom setups.

How do I run Cypress tests in parallel?

Connect your project to Cypress Cloud and run cypress run --record --parallel --key <record-key> across several CI machines or containers. Cypress Cloud load-balances specs across the machines so the suite finishes faster. Store the record key as a CI secret.

How do I keep screenshots and videos from a CI run?

Cypress saves screenshots on failure to cypress/screenshots and videos to cypress/videos when video is enabled. Upload these as CI artifacts, for example with actions/upload-artifact on GitHub, the artifacts block on GitLab, or archiveArtifacts on Jenkins.

• How to Debug Failures in Cypress Tests?
• How to Manage Test Dependencies in Cypress?
• How to Maintain and Update Test Cases in Cypress?
• What Are Page Objects in Cypress?
• What Is Integration Testing in Software Testing?