The Cypress Dashboard can integrate your Cypress tests with your GitHub workflow via commit status checks and pull request comments. A project first needs to be setup to record to the Cypress Dashboard to use GitHub integration.
GitHub Enterprise's On-premise platform is currently not supported. If you're interested in an integration with GitHub Enterprise's On-premise platform, please add your interest to our Dashboard Product Board.
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
- Go to the Dashboard Organizations page or open the organization switcher.
- Select the organization you wish to integrate with a GitHub account or GitHub organization.
- Visit the selected organization's Integrations page via the side navigation.
- Click the Install GitHub Integration button.
Install via project settings
- Select your organization in the organization switcher.
- Select the project you wish to integrate with a GitHub repository.
- Go to the project's settings page.
- Scroll down to the GitHub Integration section.
- Click the Install the Cypress GitHub App button.
Cypress GitHub app installation process
Select the desired GitHub organization or account to integrate with your Cypress Dashboard organization.
Choose to associate All repositories or only select GitHub repositories with your Cypress GitHub App installation.
All current and future repositories will be included with this installation if you choose All repositories.
- 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.
Go to the project's settings page.
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:
- Select a GitHub repository to associate with the project.
Once a GitHub repository is associated with a Cypress project, the GitHub integration will be immediately enabled:
You can also see all GitHub Integration enabled Cypress projects within your organizations Integrations page:
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.
Or one check per spec file.
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:
Disable status checks
GitHub status checks are optional, and can be disabled within a project's GitHub integration settings:
Pull request comments
The Cypress GitHub App can provide detailed test information within pull requests via comments that include:
- Run statistics, such as tests passed, failed, skipped, and over-limit.
- Run context details:
- The associated Cypress project
- Final run status (passed, failed, etc)
- Commit SHA linking to the GitHub commit
- The time the run started and finished as well as the duration.
- Operating system version and browser version.
- Run failures:
- The first 10 failures are displayed with a link to more.
- Each failed test links back to the associated failure within the Cypress Dashboard.
- Screenshot thumbnails are also provided with each failure to conveniently provide context.
An example of a Cypress pull-request comment can be seen below:
Disable PR comments
PR comments and failure screenshot thumbnails are optional, and can be disabled if not needed within a project's GitHub Integration settings:
Uninstall the Cypress GitHub app
You can uninstall the Cypress GitHub app from GitHub by performing the following steps:
- Go into your organization's Settings from within GitHub.
- Click on Installed GitHub Apps.
- Click Configure beside the Cypress app.
- Click Uninstall below the "Uninstall Cypress" section.
If you have any insights or feedback on how to improve Cypress GitHub Integration, please reach out via our official Dashboard Product Board.