{ "doc": { "id": "app/continuous-integration/github-actions", "title": "Run Cypress tests in GitHub Actions: A Step-by-Step Guide", "description": "Set up GitHub Actions to run Cypress tests, cache dependencies and build artifacts, and parallelize Cypress tests.", "section": "app", "source_path": "/llm/markdown/app/continuous-integration/github-actions.md", "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c", "updated_at": "2026-05-07T17:44:31.931Z", "headings": [ { "id": "app/continuous-integration/github-actions#run-cypress-in-github-actions", "text": "Run Cypress in GitHub Actions", "level": 1 }, { "id": "app/continuous-integration/github-actions#what-youll-learn", "text": "What you'll learn", "level": 5 }, { "id": "app/continuous-integration/github-actions#github-actions-cypress-screencasts", "text": "GitHub Actions + Cypress Screencasts", "level": 2 }, { "id": "app/continuous-integration/github-actions#cypress-github-action", "text": "Cypress GitHub Action", "level": 2 }, { "id": "app/continuous-integration/github-actions#version-number-selection", "text": "Version Number Selection", "level": 3 }, { "id": "app/continuous-integration/github-actions#basic-setup", "text": "Basic Setup", "level": 2 }, { "id": "app/continuous-integration/github-actions#testing-on-github-with-installed-browsers", "text": "Testing on GitHub with Installed Browsers", "level": 2 }, { "id": "app/continuous-integration/github-actions#testing-with-cypress-docker-images", "text": "Testing with Cypress Docker Images", "level": 2 }, { "id": "app/continuous-integration/github-actions#caching-dependencies-and-build-artifacts", "text": "Caching Dependencies and Build Artifacts", "level": 2 }, { "id": "app/continuous-integration/github-actions#parallelization", "text": "Parallelization", "level": 2 }, { "id": "app/continuous-integration/github-actions#install-job", "text": "Install Job", "level": 3 }, { "id": "app/continuous-integration/github-actions#worker-jobs", "text": "Worker Jobs", "level": 3 }, { "id": "app/continuous-integration/github-actions#setting-up-parallelization", "text": "Setting up Parallelization", "level": 4 }, { "id": "app/continuous-integration/github-actions#specifying-browsers-in-parallel-builds", "text": "Specifying Browsers in Parallel Builds", "level": 3 }, { "id": "app/continuous-integration/github-actions#using-cypress-cloud-with-github-actions", "text": "Using Cypress Cloud with GitHub Actions", "level": 2 }, { "id": "app/continuous-integration/github-actions#cypress-real-world-example-with-github-actions", "text": "Cypress Real World Example with GitHub Actions", "level": 2 }, { "id": "app/continuous-integration/github-actions#common-problems-and-solutions", "text": "Common Problems and Solutions", "level": 2 }, { "id": "app/continuous-integration/github-actions#re-run-jobs-passing-with-empty-tests", "text": "Re-run jobs passing with empty tests", "level": 3 }, { "id": "app/continuous-integration/github-actions#pull-requests-commit-message-is-merge-sha-into-sha", "text": "Pull requests commit message is merge SHA into SHA", "level": 3 }, { "id": "app/continuous-integration/github-actions#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Run Cypress in GitHub Actions" } ] }, { "type": "heading", "depth": 5, "children": [ { "type": "text", "value": "What you'll learn" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to set up Cypress tests in GitHub Actions" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to cache dependencies and build artifacts" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to parallelize Cypress tests in GitHub Actions" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "How to use Cypress Cloud with GitHub Actions" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "GitHub offers developers " }, { "type": "link", "title": null, "url": "https://github.com/features/actions", "children": [ { "type": "text", "value": "Actions" } ] }, { "type": "text", "value": " that provide a way to automate, customize, and execute your software development workflows within your GitHub repository. Detailed documentation is available in the " }, { "type": "link", "title": null, "url": "https://docs.github.com/en/actions", "children": [ { "type": "text", "value": "GitHub Action Documentation" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "GitHub Actions + Cypress Screencasts" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/USX6AntcPyg", "children": [ { "type": "text", "value": "What is Continuous Integration?" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/N0TOFWy1Xvg", "children": [ { "type": "text", "value": "Actions & Workflows" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/vVr7DXDdUks", "children": [ { "type": "text", "value": "Understanding how to configure a workflow" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/23ZGSrmbV_4", "children": [ { "type": "text", "value": "Running Tests in GitHub Actions CI/CD Workflow" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/Oqq-_QZWzhg", "children": [ { "type": "text", "value": "Debugging Test Failures in CI" } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://youtu.be/96Yn_IiQUJI", "children": [ { "type": "text", "value": "Running Tests in Parallel" } ] } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Cypress GitHub Action" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Workflows can be packaged and shared as " }, { "type": "link", "title": null, "url": "https://github.com/features/actions", "children": [ { "type": "text", "value": "GitHub Actions" } ] }, { "type": "text", "value": ". GitHub maintains many, such as the " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/checkout", "children": [ { "type": "text", "value": "checkout" } ] }, { "type": "text", "value": " and " }, { "type": "link", "title": null, "url": "https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts", "children": [ { "type": "text", "value": "Upload/Download Artifact Actions" } ] }, { "type": "text", "value": " actions used below." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The official " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/cypress-io", "children": [ { "type": "text", "value": "Cypress GitHub Action" } ] }, { "type": "text", "value": " is maintained by Cypress and our community to help ease the setup of Cypress in a GitHub Action. The action provides dependency installation (via npm, yarn, or pnpm), built-in caching of Node dependencies, and additional configuration options for advanced workflows." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Version Number Selection" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "GitHub Action Version Number" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We recommend binding to the action's latest major version by specifying `v7` when using the action." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For Example:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "jobs: cypress-run: steps: - uses: cypress-io/github-action@v7" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Alternatively, as a mitigation strategy for unforeseen breaks, bind to a specific " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action/releases", "children": [ { "type": "text", "value": "release version tag" } ] }, { "type": "text", "value": ", for example `cypress-io/github-action@v7.1.0`. Read the " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action#action-version", "children": [ { "type": "text", "value": "Cypress GitHub Action documentation" } ] }, { "type": "text", "value": " for more information." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Basic Setup" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The example below is a basic CI setup and job using the " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/cypress-io", "children": [ { "type": "text", "value": "Cypress GitHub Action" } ] }, { "type": "text", "value": " to run Cypress tests within the Electron browser. This GitHub Action configuration is placed within `.github/workflows/main.yml`." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress Testson: pushjobs: cypress-run: runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v6 # Install npm dependencies, cache them correctly # and run all Cypress tests - name: Cypress run uses: cypress-io/github-action@v7 with: build: npm run build start: npm start" }, { "type": "paragraph", "children": [ { "type": "text", "value": "How this action works:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "On push to this repository, this job will provision and start a GitHub-hosted Ubuntu Linux instance to run the outlined `steps` for the declared `cypress-run` job within the `jobs` section of the configuration." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/checkout", "children": [ { "type": "text", "value": "GitHub checkout Action" } ] }, { "type": "text", "value": " is used to check out our code from our GitHub repository." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Finally, our Cypress GitHub Action will:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Install npm dependencies" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Build the project (`npm run build`)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Start the project web server (`npm start`)" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Run the Cypress tests within our GitHub repository within Electron." } ] } ] } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Testing on GitHub with Installed Browsers" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://github.com/actions/runner-images", "children": [ { "type": "text", "value": "GitHub-hosted runners" } ] }, { "type": "text", "value": " offer images with pre-installed browsers to use for testing. The `ubuntu` and `windows` runners each include Google Chrome, Mozilla Firefox, and Microsoft Edge pre-installed. The `macos` runners additionally include Apple Safari. Refer to " }, { "type": "link", "title": null, "url": "https://github.com/actions/runner-images/blob/main/README.md", "children": [ { "type": "text", "value": "GitHub Actions Runner Images" } ] }, { "type": "text", "value": " for current details." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use the action's `browser` parameter to select the desired browser. To change the above example to select Chrome instead of the default browser Electron, add `browser: chrome` as follows." } ] }, { "type": "code", "lang": null, "meta": null, "value": "- name: Cypress run uses: cypress-io/github-action@v7 with: build: npm run build start: npm start browser: chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "For more examples, see the action's " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action#browser", "children": [ { "type": "text", "value": "Browser" } ] }, { "type": "text", "value": " section." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you are specifying a browser in a parallel job, see " }, { "type": "link", "title": null, "url": "#Specifying-Browsers-in-Parallel-Builds", "children": [ { "type": "text", "value": "Specifying Browsers in Parallel Builds" } ] }, { "type": "text", "value": " for more info on how to avoid errors during runs due to GitHub runner images being updated with the latest browsers." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Testing with Cypress Docker Images" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "GitHub Actions provides the option to specify a container image for the job. Cypress offers various " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images", "children": [ { "type": "text", "value": "Docker Images" } ] }, { "type": "text", "value": " for running Cypress locally and in CI." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Note that GitHub Actions " }, { "type": "link", "title": null, "url": "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idcontainer", "children": [ { "type": "text", "value": "requires using a Linux runner" } ] }, { "type": "text", "value": " when specifying a container image. It does not support running Docker images on Windows or macOS runners." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Below, we extend the previous example by adding the `container` attribute using a " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images/tree/master/browsers", "children": [ { "type": "text", "value": "cypress/browsers" } ] }, { "type": "text", "value": " Docker image which also includes Google Chrome. We are using the Node.js short-form tag to select a `cypress/browsers` image built with the corresponding Node.js version. To specify instead an exact set of browser versions, visit the " }, { "type": "link", "title": null, "url": "https://hub.docker.com/r/cypress/browsers", "children": [ { "type": "text", "value": "Docker Hub cypress/browsers" } ] }, { "type": "text", "value": " page and view the available long-form tags, for example `cypress/browsers:node-22.15.0-chrome-136.0.7103.92-1-ff-138.0.1-edge-136.0.3240.50-1`. Using a Cypress Docker image allows our tests to execute without any influence from browser version changes in the GitHub runner image." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress Tests using Cypress Docker Imageon: pushjobs: cypress-run: runs-on: ubuntu-24.04 container: image: cypress/browsers:22.15.0 options: --user 1001 steps: - name: Checkout uses: actions/checkout@v6 - name: Cypress run uses: cypress-io/github-action@v7 with: build: npm run build start: npm start browser: chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you are testing with Firefox, you must specify the non-root user `1001` as above. Refer to " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images#firefox-not-found", "children": [ { "type": "text", "value": "Firefox not found" } ] }, { "type": "text", "value": " for more information." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Caching Dependencies and Build Artifacts" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When working with actions that have multiple jobs, it is recommended to have an initial \"install\" job that will download any dependencies and build your app, and then cache these assets for use later by subsequent jobs." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The Cypress GitHub Action will automatically cache and restore your Node dependencies for you." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For build assets, you will need to cache and restore them manually." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `install` job below uses the " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/upload-a-build-artifact", "children": [ { "type": "text", "value": "upload-artifact" } ] }, { "type": "text", "value": " action and saves the state of the `build` directory for the `cypress-run` worker job." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/download-a-build-artifact", "children": [ { "type": "text", "value": "download-artifact" } ] }, { "type": "text", "value": " action retrieves the `build` directory saved in the `install` job, as seen below in the `cypress-run` worker job." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress Tests with Dependency and Artifact Cachingon: pushjobs: install: runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v6 - name: Cypress install uses: cypress-io/github-action@v7 with: # Disable running of tests within install job runTests: false build: npm run build - name: Save build folder uses: actions/upload-artifact@v6 with: name: build if-no-files-found: error path: build cypress-run: runs-on: ubuntu-24.04 needs: install steps: - name: Checkout uses: actions/checkout@v6 - name: Download the build folder uses: actions/download-artifact@v7 with: name: build path: build - name: Cypress run uses: cypress-io/github-action@v7 with: start: npm start browser: chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "View GitHub's guide on " }, { "type": "link", "title": null, "url": "https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts", "children": [ { "type": "text", "value": "Storing workflow data as artifacts" } ] }, { "type": "text", "value": " for more info." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Parallelization" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": " offers the ability to " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md", "children": [ { "type": "text", "value": "parallelize and group test runs" } ] }, { "type": "text", "value": " along with additional insights and " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/analytics/overview.md", "children": [ { "type": "text", "value": "analytics" } ] }, { "type": "text", "value": " for Cypress tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using parallelization with the Cypress GitHub Action requires setting up recording to " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "GitHub Actions offers a " }, { "type": "link", "title": null, "url": "https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix", "children": [ { "type": "text", "value": "matrix strategy" } ] }, { "type": "text", "value": " for declaring different job configurations for a single job definition. Jobs declared within a matrix strategy can run in parallel, which enables us to run multiples instances of Cypress at the same time, as we will see later in this section." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Before diving into an example of a parallelization setup, it is important to understand the two different types of GitHub Action jobs that we will declare:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Install Job: A job that installs and caches dependencies that will be used by subsequent jobs later in the GitHub Action workflow." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Worker Job: A job that handles the execution of Cypress tests and depends on the install job." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Install Job" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The separation of installation from test running is necessary when running parallel jobs. It allows for the reuse of various build steps aided by caching." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "First, we'll define the `install` step that will be used by the worker jobs defined in the matrix strategy." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For the `steps`, notice that we pass `runTests: false` to the Cypress GitHub Action to instruct it only to install and cache Cypress and npm dependencies without running the tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/upload-a-build-artifact", "children": [ { "type": "text", "value": "upload-artifact" } ] }, { "type": "text", "value": " action will save the state of the `build` directory for the worker jobs." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress Testson: pushjobs: install: runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v6 - name: Cypress install uses: cypress-io/github-action@v7 with: # Disable running of tests within install job runTests: false build: npm run build - name: Save build folder uses: actions/upload-artifact@v6 with: name: build if-no-files-found: error path: dist" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Worker Jobs" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Next, we define the worker job named \"cypress-run\" that will run Cypress tests as part of a parallelized matrix strategy." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `download-artifact` action will retrieve the dist directory saved in the install job." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress Testson: pushjobs: install: # ... omitted install job from above cypress-run: runs-on: ubuntu-24.04 needs: install strategy: # don't fail the entire matrix on failure fail-fast: false matrix: # run copies of the current job in parallel containers: [1, 2, 3, 4, 5] steps: - name: Checkout uses: actions/checkout@v6 - name: Download the build folder uses: actions/download-artifact@v7 with: name: build - name: Cypress run uses: cypress-io/github-action@v7 with: record: true parallel: true group: 'UI-Chrome' start: npm start" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Ensure Correct Container" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If a Docker container was used in the install job, the same Docker container must also be used in the worker jobs." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Setting up Parallelization" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To set up multiple containers to run in parallel, the matrix option of the strategy configuration can be set to containers: [1, 2, 3, 4, 5], where the number of items defined in the containers array will be how many instances of the job will start up." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For instance, `containers: [1, 2, 3, 4, 5]` will provision five worker instances to run in parallel. For our purposes, the array's values are arbitrary and aren't used in the steps." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Specifying Browsers in Parallel Builds" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When GitHub deploys new runner image versions containing updated browser versions, and the deployment is still in progress, the workflow \"Set up job\" phase randomly uses either an old or a new runner image version. Your test run might fail if Cypress Cloud detects differences in the browser versions between parallel jobs." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To work around this issue, and if you specify a browser other than the default Electron browser in parallel mode, we recommend using a " }, { "type": "link", "title": null, "url": "#Testing-with-Cypress-Docker-Images", "children": [ { "type": "text", "value": "cypress/browsers" } ] }, { "type": "text", "value": " Docker image which then uses one consistent browser version. This shields the workflow from browser version changes due to possible incomplete GitHub runner image deployments." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "As mentioned in " }, { "type": "link", "title": null, "url": "#Testing-with-Cypress-Docker-Images", "children": [ { "type": "text", "value": "Testing with Cypress Docker Images" } ] }, { "type": "text", "value": ", this option is only available with GitHub Actions Linux runners." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Using Cypress Cloud with GitHub Actions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "In the GitHub Actions configuration, we have defined in the previous section, we are leveraging three useful features of " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/introduction.md", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ":" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": true, "children": [ { "type": "listItem", "spread": true, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/get-started/setup.md", "children": [ { "type": "text", "value": "Recording test results with the `record: true` option" } ] }, { "type": "text", "value": " to " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ":" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "In-depth and shareable " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/recorded-runs.md#Latest-Runs", "children": [ { "type": "text", "value": "test reports" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Visibility into test failures via quick access to " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/test-replay.md", "children": [ { "type": "text", "value": "Test Replay" } ] }, { "type": "text", "value": ", error messages, stack traces, screenshots, videos, and contextual details." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md", "children": [ { "type": "text", "value": "Integrating testing with the pull-request (PR) process" } ] }, { "type": "text", "value": " via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Status-checks", "children": [ { "type": "text", "value": "commit status check guards" } ] }, { "type": "text", "value": " and convenient " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Pull-request-comments", "children": [ { "type": "text", "value": "test report comments" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md", "children": [ { "type": "text", "value": "Detecting flaky tests" } ] }, { "type": "text", "value": " and surfacing them via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md#Slack", "children": [ { "type": "text", "value": "Slack alerts" } ] }, { "type": "text", "value": " or " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/flaky-test-management.md#GitHub", "children": [ { "type": "text", "value": "GitHub PR status checks" } ] }, { "type": "text", "value": "." } ] } ] } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/parallelization.md", "children": [ { "type": "text", "value": "Parallelizing test runs" } ] }, { "type": "text", "value": " and optimizing their execution via " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/smart-orchestration/load-balancing.md#Balance-strategy", "children": [ { "type": "text", "value": "intelligent load-balancing" } ] }, { "type": "text", "value": " of test specs across CI machines with the `parallel: true` option." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Organizing and consolidating multiple `cypress run` calls by labeled groups into a single report within " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ". In the example above, we use the `group: \"UI-Chrome\"` option to organize all UI tests for the Chrome browser into a group labeled \"UI - Chrome\" in the " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": " report." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Cypress Real World Example with GitHub Actions" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A complete CI workflow against multiple browsers, viewports, and operating systems is available in the Cypress Real World App." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Clone the " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-realworld-app", "children": [ { "type": "text", "value": "Real World App (RWA)" } ] }, { "type": "text", "value": " and refer to the " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-realworld-app/blob/develop/.github/workflows/main.yml", "children": [ { "type": "text", "value": ".github/workflows/main.yml" } ] }, { "type": "text", "value": " file." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To see additional how-to examples, you can also refer to our " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action", "children": [ { "type": "text", "value": "Cypress GitHub Action repo" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Common Problems and Solutions" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Re-run jobs passing with empty tests" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "We recommend passing the `GITHUB_TOKEN` secret (created by the GH Action automatically) as a system environment variable in CI/CD. This will allow the accurate identification of each build to avoid confusion when re-running a build." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress testson: pushjobs: cypress-run: name: Cypress run runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v6 - name: Cypress run uses: cypress-io/github-action@v7 with: record: true env: # pass GitHub token to detect new build vs re-run build GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}" }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Pull requests commit message is `merge SHA into SHA`" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "You can overwrite the commit message sent to Cypress Cloud by setting a system environment variable in CI/CD. See " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action/issues/124", "children": [ { "type": "text", "value": "Issue #124" } ] }, { "type": "text", "value": " for more details." } ] }, { "type": "code", "lang": null, "meta": null, "value": "name: Cypress testson: pushjobs: cypress-run: name: Cypress run runs-on: ubuntu-24.04 steps: - name: Checkout uses: actions/checkout@v6 - name: Cypress run uses: cypress-io/github-action@v7 with: record: true env: # overwrite commit message sent to Cypress Cloud COMMIT_INFO_MESSAGE: ${{github.event.pull_request.title}} # re-enable PR comment bot COMMIT_INFO_SHA: ${{github.event.pull_request.head.sha}}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "We also recommend adding `COMMIT_INFO_SHA` to re-enable " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Pull-request-comments", "children": [ { "type": "text", "value": "Cypress bot PR comments" } ] }, { "type": "text", "value": ". See " }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action/issues/124#issuecomment-716584972", "children": [ { "type": "text", "value": "this comment" } ] }, { "type": "text", "value": " for more details." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://www.youtube.com/watch?v=gokM_zEmWLA", "children": [ { "type": "text", "value": "Test anything that runs in the browser with Cypress and GitHub Actions" } ] } ] } ] } ] } ] }, "token_estimate": 2721 }