Workflow:Cypress io Cypress Binary Build and Release
| Knowledge Sources | |
|---|---|
| Domains | Release_Engineering, CI_CD, Build_Systems |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for building, packaging, testing, and publishing the Cypress binary and npm package across all supported platforms (macOS, Linux, Windows).
Description
This workflow covers the internal Cypress team's release pipeline, from determining the next version number through building platform-specific Electron binaries, running system tests against the built artifacts, and publishing to npm and the CDN. The process involves V8 snapshot generation for startup performance, code signing for macOS and Windows, and coordinated CI jobs across CircleCI and GitHub Actions.
Key outputs:
- Platform-specific Cypress binaries (macOS arm64/x64, Linux x64, Windows x64)
- Published cypress npm package on the npm registry
- Binary artifacts uploaded to the Cypress CDN
- Changelog entries documenting changes since the last release
Usage
Execute this workflow when preparing a new Cypress release, whether a patch, minor, or major version. This is used by the Cypress core team after feature development and stabilization on the develop branch. The workflow is also used to produce pre-release (beta) builds for testing before a stable release.
Execution Steps
Step 1: Determine Next Version
Analyze the commit history since the last release using conventional commit messages to determine the appropriate version bump (patch, minor, or major). The get-next-version script examines commits across both the develop and main branches to compute the semantic version increment.
Key considerations:
- Conventional commit prefixes (fix:, feat:, BREAKING CHANGE:) drive version determination
- The version applies to both the npm package and the binary
- Pre-release versions append a beta tag with a build number
- The .node-version file constrains the required Node.js version for builds
Step 2: Build V8 Snapshots
Generate V8 heap snapshots that capture the initialized state of Cypress's module graph, enabling near-instant startup in production. The v8-snapshot-require and packherd-require packages work together to serialize module state into a binary snapshot that Electron loads at startup.
Key considerations:
- Snapshots must be generated per-platform due to V8 binary format differences
- The snapshot entry point loads the server's start-cypress module
- Snapshot-incompatible modules are marked as deferred (loaded from filesystem at runtime)
- Snapshot generation is the most time-consuming build step
Step 3: Package Electron Binary
Use electron-builder to package the Cypress server, driver, runner, and all dependencies into a distributable Electron application. The after-pack hook performs extensive post-packaging steps including pruning development dependencies, copying additional assets, and cleaning up platform-specific files.
Key considerations:
- Separate builds target macOS (arm64 + x64), Linux (x64), and Windows (x64)
- The electron-builder.json configuration defines packaging options and hooks
- The after-pack hook copies icons, extension assets, and the V8 snapshot into the package
- Build output is compressed into platform-specific archives (zip, tar.gz)
Step 4: Code Sign Binaries
Sign the macOS binary with an Apple Developer certificate and submit it for notarization. Sign the Windows binary using ssl.com's CodeSignTool for OV (Organization Validation) code signing. Code signing ensures binary integrity and prevents OS security warnings.
Key considerations:
- macOS signing uses the after-sign hook with electron-notarize
- Windows signing uses the windows-sign.js script with CodeSignTool
- Signing credentials are stored as CI environment variables
- Notarization is asynchronous and must complete before distribution
Step 5: Run System Tests
Execute the comprehensive system test suite against the built binary to verify end-to-end functionality. System tests run real Cypress projects with various configurations, frameworks, and error scenarios to validate the binary before release.
Key considerations:
- System tests use Docker containers for reproducible environments
- Tests cover E2E and component testing across multiple frameworks
- Failure in system tests blocks the release pipeline
- Tests validate cross-origin behavior, plugin systems, and error handling
Step 6: Publish npm Package and Binary
Publish the cypress npm package to the npm registry and upload the platform binaries to the Cypress CDN. The npm-release script coordinates publishing of both the main package and any independently-released @cypress/* packages. The prepare-release-artifacts script transforms pre-release packages into stable releases.
Key considerations:
- Binary upload uses the scripts/binary.js dispatch script
- The npm package includes a postinstall hook that downloads the correct platform binary
- Pre-release packages are promoted to stable by patching buildInfo.stable
- CDN cache may need manual purging via Cloudflare if stale assets persist
Step 7: Verify Release and Announce
Verify the published package installs correctly and the binary downloads from the CDN. Post a GitHub commit comment with pre-release installation instructions. Update the changelog with release notes covering all changes since the previous version.
Key considerations:
- The add-install-comment script posts installation instructions to the develop branch commit
- Changelog entries follow a specific format documented in the writing-the-cypress-changelog guide
- External project testing validates the release against real-world applications
- Release announcements are coordinated across GitHub releases and community channels