GitHub Integration

In this tutorial, we will show you how to integrate your test with GitHub workflow using commit status checks as well as pull request comments.

In order to use GitHub Integration, you must setup your project for record in the Cypress Dashboard.

Currently, the GitHub Enterprise’s On-premise platform is not supported. If you want an integration with the GitHub Enterprise On-premise platform, you will need to add your interest to Cypress’s Dashboard Product Board (https://portal.productboard.com/cypress-io/1-cypress-dashboard)

The GitHub Integration depends on your CI environment to reliably provide commit SHA data (this is typically done via an environment variable). This is not a general problem, however, if you are experiencing GitHub integration issues with your CI setup. You can send your git information to cypress using the guidelines contained in the (

Install the Cypress GitHub app

You will need to install Cypress GitHub App, before you will be able to enable GitHub integration for your Cypress projects.

The GitHub App installation process can be started from your organization’s setting page or a project’s setting page in the Cypress Dashboard.

Install via organization integration settings

  1. Navigate to the Dashboard Organization page or you open the organization switcher.
  2. Then you select the organization that you wish to integrate with a GitHub account or you with a GitHub organization
  3. Visit the selected organization’s Integration page through the side navigation.
  4. Then click on the Install GitHub Integration button.

Install via project settings

  1. First, you will need to select the organization in the organization switcher.
  2. Then, you should select the project that you wish to integrate with a GitHub repository.
  3. Then the next thing will be to go to the settings page.
  4. Scroll down to the GitHub integration section
  5. Click on the install the Cypress GitHub App

Cypress GitHub app installation process

You will be directed to GitHub.com to complete the installation, once you start the GitHub installation process via a Cypress Organization’s settings or a project’s settings:

  1. You will need to select the desired GitHub organization or account in order to integrate with your Cypress Dashboard organization.
  2. You can then choose to either associate all repositories or only select the GitHub repositories with your Cypress GitHub installation.
  3. Finally, you will need to click the Install button to complete the installation.

Enabling GitHub integration for a project

Once you have completed the Cypress GitHub App installation for your organization, you can now enable GitHub Integration for any Cypress project.

  1. The first step is to go to the project’s settings page.
  2. Then you will need to scroll down to the GitHub Integration section
  3. Select the GitHub repository that you want to associate with the project.

Immediately you associate a GitHub repository with your Cypress project, the GitHub integration will be enabled.

You will now be able to see all the GitHub integration enabled Cypress projects that are within your Organization Integrations page.

Status checks

In the case where you have enabled status checks within your project’s GitHub integration settings, the Cypress Dashboard will report cypress test statuses to GitHub for related commits. A status check will help you prevent merging a commit or pull-request into the rest of your code base until all of your Cypress tests have passed.

The Cypress GitHub app will report commit status checks in two separate styles:

  • The Cypress check per run group
  • Or a check per spec file

Every status checks reports the number of test failures or passes, and the associated Detail links direct you to the test run’s page within the Cypress Dashboard, in order to help you debug the error with the aid of the error messages, stack traces, screenshots, and video recordings.

Disable status checks

GitHub status checks are an optional feature, and can be disabled within the GitHub integration settings of your project.

Pull request comments

The Cypress GitHub App can provide you with detailed test information within pull requests via comment which include:

  • Run statistics, like tests passed, failed, skipped, and over-linit.
  • Run context details:
    • The associated Cypress project
    • Final run status (passed, failed, etc)
    • Commit SHA that links to the GitHub commit
    • The details of the time the run started and the time it finished, as well as the duration.
    • The operating system version as well as the browser version.
  • Run failures
    • The first 10 failures will be displayed with a link to more.
    • Each failed test will link back to the associated failure within the Cypress Dashboard.
    • Screenshot thumbnails will also be provided with each failure to conveniently provide context.

Disable PR comments

The PR comments feature is an optional feature, and can be disabled within the GitHub integration settings of your project.

Uninstall the Cypress GitHub app

To uninstall the Cypress GitHub app from GitHub, you will need to perform the following steps:

  1. First you will need to go into your organization’s Settings from within GitHub.
  2. Then, you click on Installed GitHub Apps.
  3. Click on Configure beside the Cypress app.
  4. Finally, you can then click on Uninstall below the “Uninstall Cypress” section.