To run Cypress end-to-end tests in GitLab CI/CD, define a test job in .gitlab-ci.yml that installs your project dependencies, starts the application, waits until it is ready, and runs Cypress. A pinned Cypress browser image gives the job a predictable Node.js and browser environment; GitLab artifacts preserve screenshots and videos for troubleshooting.
What a Cypress GitLab pipeline needs
A push to your repository can trigger a GitLab pipeline that runs Cypress on a Linux runner. The test job should handle four tasks in order:
- Install the exact dependencies recorded in the lockfile with
npm ci. - Start the application or test environment.
- Wait for the application to respond before testing.
- Run Cypress in headless mode with
npx cypress runor an npm script that invokes it.
Cypress describes the purpose of this setup as running end-to-end and component tests against the application on each commit, so a broken user flow can fail the build rather than ship. See Cypress continuous integration documentation.
Choose a job image and browser
The job image determines the Node.js and browser environment available to Cypress. A standard Node image can work if you install and configure the required browser dependencies yourself. For a simpler browser setup, use a maintained Cypress image and pin its tag so changes to Node or browser versions do not arrive unexpectedly. Cypress documents that its maintained browser images include Chrome, Firefox, and Microsoft Edge.
For example, cypress/browsers:22.15.0 can be used to run Firefox tests with npx cypress run --browser firefox. The tag is an example of a pinned image, not a requirement for every project. Check Cypress’s Docker images documentation when selecting a tag compatible with your project.
Configure a basic GitLab CI job
Add a job to the repository’s .gitlab-ci.yml. This example installs dependencies, starts the app, waits for the local server, then runs Cypress. Replace the readiness command and URL with the health-check endpoint and startup command used by your application.
stages:
- test
test:
image: cypress/browsers:22.15.0
stage: test
variables:
CYPRESS_BASE_URL: "http://127.0.0.1:3000"
script:
- npm ci
- npm start &
- npx wait-on http://127.0.0.1:3000
- npx cypress run --browser firefox
artifacts:
when: always
paths:
- cypress/videos/**/*.mp4
- cypress/screenshots/**/*.png
expire_in: 1 dayThis example assumes the project has a suitable wait-on dependency and serves the application on port 3000. If it does not, add a readiness utility to the project or use an equivalent health check. Starting the server and Cypress back-to-back without checking readiness can create a race: Cypress may begin before the app is listening. A fixed sleep is less reliable because startup time varies.
Set CYPRESS_BASE_URL to the environment under test when it is not the local server in the example. Cypress also supports CYPRESS_-prefixed overrides for settings such as reporter, timeout, and viewport. See Cypress CI configuration guidance.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Cache dependencies and keep failure evidence
GitLab caches can reduce repeated downloads across jobs. Cypress’s example uses a branch-derived cache key and directories including node_modules/, .npm/, and cache/Cypress. Adapt the paths to the package manager and Cypress binary location in your project.
Artifacts serve a different purpose from caches: artifacts make job output available after a run, while caches are intended to speed up later jobs. Set when: always so screenshots and videos are uploaded even when tests fail. Use expire_in to choose how long GitLab retains them; the one-day period in the example is a configuration choice, not a general retention rule.
Run browser suites in parallel
For longer suites, GitLab can create multiple worker jobs with its parallel setting. Cypress documents a pattern with an install job followed by workers. To have Cypress Cloud distribute test work and consolidate results, configure the project for Cloud and run workers with --record --parallel; use --group to label a browser suite.
Recording and Cypress Cloud parallelization require a Cloud project and record key. Store that key as a protected CI/CD variable rather than committing it in .gitlab-ci.yml. GitLab’s parallel jobs by themselves create workers; Cypress Cloud is what coordinates the recorded parallel run. See Cypress’s CI parallelization guidance.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Choose between local artifacts and Cypress Cloud
GitLab artifacts are sufficient when the main need is to inspect failure screenshots and videos. Cypress Cloud adds recorded-run reporting and can integrate with GitLab to publish a cypress/run commit status, block merges after failed runs, optionally report flaky-test status, and comment on merge requests. Some integration features are limited to paid plans. For self-managed GitLab, the instance also needs network access to the Cypress Cloud API. Details are in Cypress Cloud’s GitLab integration documentation.
Quick Recap
Common pipeline problems
- Cypress starts before the app: add a readiness check for the actual URL Cypress will visit; do not depend on a background start command alone.
- A browser is unavailable: verify the selected image tag and browser name, or choose a maintained Cypress browser image that includes the target browser.
- Tests pass locally but fail in CI: check the configured
CYPRESS_BASE_URL, app startup logs, environment variables, and whether the CI job targets the same browser and application configuration. - There is no evidence after a failure: configure screenshot and video paths as GitLab artifacts with
when: always, and confirm artifact retention suits your debugging needs. - Cloud recording is rejected: check that the project is configured for Cypress Cloud and that the protected record key is available to the pipeline context.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
