Principle:Cypress io Cypress CI Environment Configuration
| Knowledge Sources | |
|---|---|
| Domains | CI_CD, Configuration |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A CLI argument mapping mechanism that translates environment variables and command-line flags into structured server arguments for headless CI execution.
Description
CI environment configuration bridges the gap between CI pipeline configuration (environment variables, CLI flags) and the Cypress server's argument interface. The processRunOptions function validates and maps options like --record, --parallel, --group, and --ci-build-id into the argument array passed to the spawned server process.
A critical CI concern is the CYPRESS_RECORD_KEY environment variable, which authenticates recording to Cypress Cloud. The system also handles CYPRESS_CI_KEY as a fallback for backward compatibility.
Usage
Use this principle when configuring cypress run in CI pipelines, especially when enabling recording, parallelization, and grouping features.
Theoretical Basis
Option Mapping Pipeline:
CLI flags / env vars → processRunOptions() → string[] → spawn.start(args)
Key CI Options:
--record → enables recording to Cypress Cloud
--key / CYPRESS_RECORD_KEY → authentication for recording
--parallel → enables spec distribution across machines
--group <name> → groups parallel runs
--ci-build-id <id> → unique identifier for the CI build
--tag <tags> → tags for the recorded run