Skip to main content

GitHub Integration

Cypress Cloud can integrate your Cypress tests with your GitHub workflow via commit status checks and pull request comments. A project first needs to be set up to record to Cypress Cloud to use GitHub integration.

Cypress GitHub App PR
caution

The user enabling the integration must be a GitHub admin to enable repository access.

caution

GitHub Integration depends on your CI environment reliably providing a commit SHA (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 still face issues after this, please contact us.

GitHub Enterprise

tip
Premium Cypress Cloud Feature

GitHub Enterprise integration is included in our Business and Enterprise paid pricing plans.

To configure Cypress Cloud integration for your GitHub Enterprise site, first follow the instructions to install via organization integration settings below, then skip to Cypress GitHub Enterprise app installation, and finally enable the integration for a project.

Install the Cypress GitHub app

Before enabling 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 Cypress Cloud.

Install via organization integration settings

  1. Go to Cypress Cloud Organizations page or open the organization switcher.

  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.

    Install Cypress GitHub from Integrations
  4. Click the Install GitHub Integration or Install GitHub Enterprise Integration button.

Install via project settings

caution

This installation method does not apply to GitHub Enterprise.

  1. Select your organization in the organization switcher.

    Select an organization
  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 Enable GitHub button.

    Enable GitHub

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 Cloud organization.

    Select a GitHub organization
  2. Choose which repositories to associate with the Cypress GitHub App. You can choose All repositories or Only select repositories. with your Cypress GitHub App installation.

info

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

Select GitHub repositories
  1. Click the Install button to complete the installation.
danger

Cypress GitHub Enterprise app installation process

To integrate Cypress Cloud with GitHub Enterprise, you need to create a new GitHub App, copy the necessary settings and credentials from the new app, paste them into Cypress Cloud, and complete the activation process.

  1. With your Cypress Cloud organization's GitHub Enterprise page open, open a new tab or browser window and browse to your GitHub Enterprise site. Navigate to your GitHub organization → SettingsDeveloper settingsGitHub Apps. Do NOT go to OAuth Apps. Click the New GitHub App button.
Create new GitHub App
  1. Complete the Register new GitHub app section.
Configure new GitHub App
  1. Complete the Webhook section.
Configure app webhook
  1. Set the Repository Permissions. Below are the minimum permissions required for the new GitHub App.
    • Pull requests: read & write
    • Commit statuses: read & write
Configure app permissions
Configure app permissions
  1. Skip to the bottom of the form and click the Create GitHub App button. Your new GitHub App is now created, and you'll be taken to the settings page.

  2. Returning to Cypress Cloud GitHub Enterprise Integration configuration screen, populate the following values from your new GitHub App.

    • Copy the root URL of your GitHub Enterprise site to the Cypress GitHub Enterprise Server URL field.
    • Copy the App ID to the Cypress GitHub Enterprise App ID field.
    • Copy the Client ID to the Cypress GitHub Enterprise Client ID field.
    • Copy the GitHub App name to the Cypress GitHub Enterprise App name field.
    • Generate a new Client secret in GitHub by clicking on the Generate a new client secret button. Copy the new secret into the Cypress GitHub Enterprise Client secret field.
    • Generate a new private key in GitHub by clicking on the Generate a private key button. Open in a text editor and copy all of the content into the Cypress GitHub Enterprise Private key field.
Collect new app info
Generate client secret
Generate private key
  1. In Cypress Cloud, click the Next Step button, and you will be taken to the GitHub Enterprise app authorization page. Click the Authorize [your app name] button.
Authorize GitHub App
  1. On your newly-authorized GitHub App, click the Install button.
Install GitHub App
  1. Nearly there! On the GitHub App installation page, choose whether you want to install the app against all repos or select specific ones, then click the Install button.
info

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

Confirm installation of GitHub App
  1. Finally, you will be returned to Cypress Cloud. Congratulations, you have installed Cypress Cloud GitHub Enterprise integration! You are now ready to configure a GitHub Integration for a project.

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. Go to the organization's Integrations page.
Visit Organization's Integrations
  1. Scroll down to the GitHub Integration or GitHub Enterprise Integration section.
info

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
  1. Select a GitHub repository to associate 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, Cypress Cloud 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 distinct 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 Cypress Cloud to help you dig deeper into the problem via error messages, stack traces, screenshots, and video recordings:

Cypress Cloud specs tab
tip
Debugging Cypress Cloud Test Runs?

Don't rely on artifact representations or reproducing failing conditions locally. Replay the test as it executed during the recorded run with full debug capability using Test Replay.

Disable status checks

GitHub status checks are optional and can be disabled within a project's GitHub integration settings:

Status checks settings
tip
Premium Cypress Cloud Feature

Reporting on flaky status checks is included in our Team, Business and Enterprise paid pricing plans.

Pull request comments

The Cypress GitHub App can provide detailed test information within the pull requests via comments that include:

  • Run statistics, such as tests passed, failed, skipped, and over-limit.
  • Run context details:
    • The associated Cypress project
    • Run status (passed, failed, etc.)
    • Commit message
    • Commit SHA
    • The time the run started and finished, as well as the duration
  • Run failures:
    • A summary of the tests that failed
    • A link back to the associated failure within Cypress Cloud

An example of a Cypress pull-request comment can be seen below:

Cypress GitHub App PR comment

Disable PR comments

PR comments are optional and can be disabled if not needed within a project's GitHub Integration settings:

Status checks settings

Uninstall the Cypress GitHub app

You can uninstall the Cypress GitHub app from GitHub by performing the following steps:

  1. Go into your organization's Settings from within GitHub.
  2. Click on GitHub Apps.
  3. Click Configure beside the Cypress app.
  4. Click Uninstall in the "Danger Zone" section.

Troubleshooting

See Common GitHub Actions Problems and Solutions.

See also