{ "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": "ce02913654e2655ee63448bdc92bb92c7b46a619", "updated_at": "2026-04-22T19:37:51.587Z", "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\nprovide a way to automate, customize, and execute your software development\nworkflows within your GitHub repository. Detailed documentation is available\nin 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\n" }, { "type": "link", "title": null, "url": "https://github.com/features/actions", "children": [ { "type": "text", "value": "GitHub Actions" } ] }, { "type": "text", "value": ". GitHub maintains many,\nsuch as the " }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/checkout", "children": [ { "type": "text", "value": "checkout" } ] }, { "type": "text", "value": " and\n" }, { "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": "\nactions used below." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The official\n" }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/cypress-io", "children": [ { "type": "text", "value": "Cypress GitHub Action" } ] }, { "type": "text", "value": " is\nmaintained by Cypress and our community to help ease the setup of Cypress in a\nGitHub Action. The action provides dependency installation (via npm, yarn, or\npnpm), built-in caching of Node dependencies, and additional configuration\noptions 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`\nwhen using the action." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For Example:" } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "jobs:\n cypress-run:\n steps:\n - uses: cypress-io/github-action@v7" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Alternatively, as a mitigation strategy for unforeseen breaks, bind to a\nspecific\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/github-action/releases", "children": [ { "type": "text", "value": "release version tag" } ] }, { "type": "text", "value": ", for\nexample `cypress-io/github-action@v7.1.0`. Read the\n" }, { "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": "\nfor 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\n" }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/cypress-io", "children": [ { "type": "text", "value": "Cypress GitHub Action" } ] }, { "type": "text", "value": " to\nrun Cypress tests within the Electron browser. This GitHub Action configuration\nis placed within `.github/workflows/main.yml`." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "name: Cypress Tests\n\non: push\n\njobs:\n cypress-run:\n runs-on: ubuntu-24.04\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n # Install npm dependencies, cache them correctly\n # and run all Cypress tests\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n build: npm run build\n 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\nGitHub-hosted Ubuntu Linux instance to run the outlined `steps` for the\ndeclared `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": "\nis 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\nwith pre-installed browsers to use for testing. The `ubuntu` and `windows`\nrunners each include Google Chrome, Mozilla Firefox, and Microsoft Edge\npre-installed. The `macos` runners additionally include Apple Safari. Refer to\n" }, { "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": "\nfor current details." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use the action's `browser` parameter to select the desired browser. To change\nthe above example to select Chrome instead of the default browser Electron, add\n`browser: chrome` as follows." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "- name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n build: npm run build\n start: npm start\n browser: chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "For more examples, see the action's\n" }, { "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\n" }, { "type": "link", "title": null, "url": "#Specifying-Browsers-in-Parallel-Builds", "children": [ { "type": "text", "value": "Specifying Browsers in Parallel Builds" } ] }, { "type": "text", "value": "\nfor more info on how to avoid errors during runs due to GitHub runner images\nbeing 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.\nCypress offers various\n" }, { "type": "link", "title": null, "url": "https://github.com/cypress-io/cypress-docker-images", "children": [ { "type": "text", "value": "Docker Images" } ] }, { "type": "text", "value": " for running\nCypress locally and in CI." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Note that GitHub Actions\n" }, { "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.\nIt 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\n" }, { "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": "\nDocker image which also includes Google Chrome.\nWe are using the Node.js short-form tag to select a `cypress/browsers` image\nbuilt with the corresponding Node.js version.\nTo specify instead an exact set of browser versions, visit the\n" }, { "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,\nfor example `cypress/browsers:node-22.15.0-chrome-136.0.7103.92-1-ff-138.0.1-edge-136.0.3240.50-1`.\nUsing a Cypress Docker image allows our tests to execute without any influence from\nbrowser version changes in the GitHub runner image." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "name: Cypress Tests using Cypress Docker Image\n\non: push\n\njobs:\n cypress-run:\n runs-on: ubuntu-24.04\n container:\n image: cypress/browsers:22.15.0\n options: --user 1001\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n build: npm run build\n start: npm start\n 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\ninitial \"install\" job that will download any dependencies and build your app,\nand 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\ndependencies 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\n" }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/upload-a-build-artifact", "children": [ { "type": "text", "value": "upload-artifact" } ] }, { "type": "text", "value": "\naction and saves the state of the `build` directory for the `cypress-run` worker\njob." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The\n" }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/download-a-build-artifact", "children": [ { "type": "text", "value": "download-artifact" } ] }, { "type": "text", "value": "\naction retrieves the `build` directory saved in the `install` job, as seen below\nin the `cypress-run` worker job." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "name: Cypress Tests with Dependency and Artifact Caching\n\non: push\n\njobs:\n install:\n runs-on: ubuntu-24.04\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Cypress install\n uses: cypress-io/github-action@v7\n with:\n # Disable running of tests within install job\n runTests: false\n build: npm run build\n\n - name: Save build folder\n uses: actions/upload-artifact@v6\n with:\n name: build\n if-no-files-found: error\n path: build\n\n cypress-run:\n runs-on: ubuntu-24.04\n needs: install\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Download the build folder\n uses: actions/download-artifact@v7\n with:\n name: build\n path: build\n\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n start: npm start\n browser: chrome" }, { "type": "paragraph", "children": [ { "type": "text", "value": "View GitHub's guide on\n" }, { "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": "\nfor 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\n" }, { "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": "\nalong 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\nCypress tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using parallelization with the Cypress GitHub Action requires setting up\nrecording 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\n" }, { "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": "\nfor declaring different job configurations for a single job definition. Jobs\ndeclared within a matrix strategy can run in parallel, which enables us to run\nmultiples instances of Cypress at the same time, as we will see later in this\nsection." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Before diving into an example of a parallelization setup, it is important to\nunderstand 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\nby 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\non 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\nparallel 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\ndefined in the matrix strategy." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For the `steps`, notice that we pass `runTests: false` to the Cypress GitHub\nAction to instruct it only to install and cache Cypress and npm dependencies\nwithout running the tests." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The\n" }, { "type": "link", "title": null, "url": "https://github.com/marketplace/actions/upload-a-build-artifact", "children": [ { "type": "text", "value": "upload-artifact" } ] }, { "type": "text", "value": "\naction will save the state of the `build` directory for the worker jobs." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "name: Cypress Tests\n\non: push\n\njobs:\n install:\n runs-on: ubuntu-24.04\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Cypress install\n uses: cypress-io/github-action@v7\n with:\n # Disable running of tests within install job\n runTests: false\n build: npm run build\n\n - name: Save build folder\n uses: actions/upload-artifact@v6\n with:\n name: build\n if-no-files-found: error\n 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\nas part of a parallelized matrix strategy." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `download-artifact` action will retrieve the dist directory saved in the\ninstall job." } ] }, { "type": "code", "lang": "yaml", "meta": null, "value": "name: Cypress Tests\n\non: push\n\njobs:\n install:\n # ... omitted install job from above\n\n cypress-run:\n runs-on: ubuntu-24.04\n needs: install\n strategy:\n # don't fail the entire matrix on failure\n fail-fast: false\n matrix:\n # run copies of the current job in parallel\n containers: [1, 2, 3, 4, 5]\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Download the build folder\n uses: actions/download-artifact@v7\n with:\n name: build\n\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n record: true\n parallel: true\n group: 'UI-Chrome'\n 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\nmust 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\nstrategy configuration can be set to containers: [1, 2, 3, 4, 5], where the\nnumber of items defined in the containers array will be how many instances of\nthe job will start up." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For instance, `containers: [1, 2, 3, 4, 5]` will provision five worker instances\nto run in parallel. For our purposes, the array's values are arbitrary and\naren'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,\nand the deployment is still in progress,\nthe workflow \"Set up job\" phase randomly uses either an old or a new runner image version.\nYour 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,\nand if you specify a browser other than the default Electron browser in parallel mode,\nwe recommend using a\n" }, { "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.\nThis 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": ",\nthis 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\nare leveraging three useful features of\n" }, { "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": false, "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": "\nto " }, { "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\n" }, { "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\ntraces, 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": "\nvia\n" }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/github.md#Status-checks", "children": [ { "type": "text", "value": "commit status check guards" } ] }, { "type": "text", "value": "\nand convenient\n" }, { "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\nthem 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\n" }, { "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": "\nand optimizing their execution via\n" }, { "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": "\nof 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\ninto a single report within " }, { "type": "link", "title": null, "url": "https://on.cypress.io/cloud", "children": [ { "type": "text", "value": "Cypress Cloud" } ] }, { "type": "text", "value": ". In\nthe example above, we use the `group: \"UI-Chrome\"` option to organize all\nUI tests for the Chrome browser into a group labeled \"UI - Chrome\" in the\n" }, { "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\nsystems is available in the Cypress Real World App." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Clone the and refer to\nthe\n" }, { "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": "\nfile." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To see additional how-to examples, you can also refer to our\n" }, { "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\nautomatically) as a system environment variable in CI/CD. This will allow the accurate\nidentification of each build to avoid confusion when re-running a build." } ] }, { "type": "code", "lang": "yml", "meta": null, "value": "name: Cypress tests\non: push\njobs:\n cypress-run:\n name: Cypress run\n runs-on: ubuntu-24.04\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n record: true\n env:\n # pass GitHub token to detect new build vs re-run build\n 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\nsystem environment variable in CI/CD. See\n" }, { "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\ndetails." } ] }, { "type": "code", "lang": "yml", "meta": null, "value": "name: Cypress tests\non: push\njobs:\n cypress-run:\n name: Cypress run\n runs-on: ubuntu-24.04\n steps:\n - name: Checkout\n uses: actions/checkout@v6\n\n - name: Cypress run\n uses: cypress-io/github-action@v7\n with:\n record: true\n env:\n # overwrite commit message sent to Cypress Cloud\n COMMIT_INFO_MESSAGE: ${{github.event.pull_request.title}}\n # re-enable PR comment bot\n 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\n" }, { "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": ".\nSee\n" }, { "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": "\nfor 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": 2735 }