GitHub Integration

The Cypress Dashboard can integrate your Cypress tests with your GitHub workflow via commit status checks and pull-request comments.
Cypress GitHub App PR

GitHub Enterprise is currently not supported. Please contact us if you are interested in Enterprise integration.

GitHub Integration is dependent on your CI environment reliably providing commit SHA data (typically via an environment variable). This is not a problem for most users, but if you are facing GitHub integration issues with your CI setup, please make sure the git information is being sent properly by following these guidelines. If you are still facing issues after this, please contact us.

Install the Cypress GitHub app

Before you can enable GitHub integration for your Cypress projects, you must first install the Cypress GitHub App. You can start the GitHub App installation process via your organization’s settings page or a project’s settings page in the Cypress Dashboard.

Install via organization integration settings

  1. Go to the Dashboard Organizations page.
  2. Select the organization you wish to integrate with a GitHub account or GitHub organization.Select an organization
  3. Visit the selected organization’s Integrations page via the side navigation.
  4. Click the Install the Cypress GitHub App button.Install Cypress GitHub App from Integrations

Install via project settings

  1. Go to your organization’s projects page.
  2. Select the project you wish to integrate with a GitHub repository.Select a project
  3. Go to the project’s settings page.Visit project settings
  4. Scroll down to the GitHub Integration section.
  5. Click the Install the Cypress GitHub App button.Install GitHub Cypress App

Cypress GitHub app installation process

Once you’ve started the GitHub App installation process via a Cypress organization's settings or a project's settings, you will be directed to GitHub.com to complete the installation:

  1. Select the desired GitHub organization or account to integrate with your Cypress Dashboard organization.

    Select a GitHub organization
  2. Choose to associate All repositories or only select GitHub repositories with your Cypress GitHub App installation.

    Select All GitHub repositories

    All current and future repositories will be included with this installation if you choose All repositories.

    Select specific GitHub repositories
  3. Click the Install button to complete the installation.

Enabling GitHub integration for a project

After completing the Cypress GitHub App installation for your organization you can now enable GitHub Integration for any Cypress project.

  1. Visit a project’s setting page, and scroll down to the GitHub Integration section.

    You can quickly get to a project’s GitHub Integrations settings, by clicking on the Configure link of the desired project within an organization’s Integrations page:

    Org GitHub Integration settings
  2. Select a GitHub repository to associated with the project.

    Associate GitHub repo with Cypress project

Once a GitHub repository is associated with a Cypress project, the GitHub integration will be immediately enabled:
GitHub integration enabled for Cypress project

You can also see all GitHub Integration enabled Cypress projects within your organizations Integrations page:
Integrations page

Status checks

If status checks are enabled within a project’s GitHub integration settings, the Cypress Dashboard will report Cypress test statuses to GitHub for related commits. Status checks help prevent merging a commit or pull-request into the rest of your codebase until all your Cypress tests have passed.

The Cypress GitHub App reports commit status checks in two separate styles:

  • One check per run group.

    Status checks per group
  • Or one check per spec file.

    Status checks per spec

Each status check will report the number of test failures or passes, and the associated Details link will direct you to the test run’s page within the Cypress Dashboard to help you dig deeper into the problem via error messages, stack traces, screenshots, and video recordings: