XQA
Back to Test Automation
2026-03-258 min read

Cypress GitHub Enterprise app installation process (Test Automation)

Learn Cypress GitHub Enterprise app installation process (Test Automation) step by step with clear examples and exercises.

Why This Matters

Welcome to this full guide on integrating GitHub Enterprise with Cypress, a powerful end-to-end JavaScript test runner for web applications. You'll learn about the installation process, configuration, and best practices to streamline your test automation workflow.

Why This Matters

Integrating GitHub Enterprise with Cypress offers numerous benefits:

  1. Continuous Integration (CI): Automate your tests as part of your CI pipeline, ensuring that any code changes don't break the application.
  2. Improved Test Coverage: With GitHub Enterprise integration, you can easily track test runs and manage flaky tests.
  3. Collaborative Testing: Share test results with team members for quicker feedback and faster issue resolution.
  4. Centralized Test Management: Store all your test artifacts in one place, making it easier to maintain and manage tests over time.
  5. Enhanced Reporting: Generate detailed reports on test runs, helping you identify trends and areas for improvement.
  6. Seamless Integration with GitHub Issues: Link test results directly to GitHub issues, providing context and facilitating issue tracking.
  7. Scalability: Easily scale your tests across multiple projects and repositories within your organization.
  8. Security: use GitHub Enterprise's security features, such as two-factor authentication and access controls, to secure your test automation workflow.
  9. Integration with Other Tools: Extend the functionality of your test suite by integrating it with other tools like Slack, Jira, or Trello.
  10. Cost Efficiency: By using GitHub Enterprise, you can reduce costs associated with maintaining separate testing infrastructure.

Prerequisites

To follow this tutorial, you'll need the following prerequisites:

  1. Node.js (v10.16.0 or higher) installed on your machine. Install Node.js
  2. A GitHub account and a GitHub Enterprise instance set up.
  3. Access to your organization's settings in the GitHub Enterprise instance.
  4. Basic knowledge of JavaScript, Git, and test automation concepts.
  5. Familiarity with Cypress (if you are new to Cypress, we recommend going through the official documentation first).
  6. Familiarity with GitHub Actions or another CI/CD tool to run tests as part of your pipeline.

Core Concept

Cypress GitHub Enterprise integration allows you to integrate Cypress tests with your GitHub workflow via commit status checks and pull request comments. To achieve this, we will:

  1. Install the Cypress GitHub App.
  2. Enable GitHub integration for a project.
  3. Configure status checks and pull request comments.
  4. Set up GitHub Actions to run tests as part of your CI pipeline.

Installing the Cypress GitHub App

To install the Cypress GitHub app, follow these steps:

Via Organization Integration Settings

  1. Navigate to your GitHub Enterprise instance at https://.com.
  2. Sign in with your GitHub account credentials.
  3. Click on your organization's name in the top-right corner of the navigation bar and select "Settings" from the dropdown menu.
  4. In the left sidebar, click on "Developers."
  5. Scroll down to the "GitHub Apps" section and click on "New GitHub App."
  6. Fill in the required details for your app (e.g., Name, Homepage URL, and Description).
  7. Under "Installation," select "Enterprise" as the installation scope.
  8. Click on "Create GitHub App."
  9. Follow the instructions provided by Cypress to install the GitHub App for your organization.

Enabling GitHub Integration for a Project

Once you have installed the Cypress GitHub App, you can enable integration for specific projects:

  1. Navigate to your GitHub Enterprise instance at https://.com.
  2. Sign in with your GitHub account credentials.
  3. Click on the repository that you want to integrate with Cypress.
  4. In the left sidebar, click on "Settings."
  5. Scroll down to the "Webhooks" section and click on "Add webhook."
  6. Enter the following URL as the payload URL: https://api.cypress.io/github/webhooks// (Replace ` and ` with your organization's slug and repository name, respectively.)
  7. Select "Just the push event" as the trigger for this webhook.
  8. Click on "Add webhook."

Configuring Status Checks and Pull Request Comments

To configure status checks and pull request comments:

  1. In your project's root directory, create a cypress.json file if it doesn't already exist.
  2. Add the following configuration to the cypress.json file:
{
"env": {
"CYPRESS_GITHUB_TOKEN": "<your-github-token>"
},
"integrationFolder": "integration",
"video": false,
"screenshotsFolder": "screenshots",
"reporter": "mochawesome",
"reporterOptions": {
"reportDir": "reports/mocha",
"overwrite": false,
"html": true
},
"baseUrl": "<your-app-url>",
"videoUploadOnPasses": false,
"viewportWidth": 1280,
"viewportHeight": 720,
"specPattern": "integration/**/*.js"
}

Replace ` with your GitHub personal access token and ` with the URL of your web application.

  1. Run the following command to install Cypress and its dependencies:
npm install cypress --save-dev
  1. Create a new integration file in the integration folder (e.g., example_spec.js). Write your test cases in this file.
  2. Set up GitHub Actions to run your tests as part of your CI pipeline. You can find an example GitHub Actions workflow in the Cypress Example KitchenSink repository.
  3. Push your changes to the repository, and observe the status checks and pull request comments on GitHub.

Worked Example

In this worked example, we will demonstrate how to integrate Cypress with GitHub Enterprise for a simple web application.

Step 1: Install Dependencies

First, let's create a new project and install the necessary dependencies:

mkdir my-app && cd my-app
npm init -y
npm install express cypress --save

Create a simple Express server to serve your web application:

// server.js
const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
res.send('Hello World!');
});

app.listen(port, () => {
console.log(`Server running at http://localhost:${port}`);
});

Start the server with:

node server.js

Step 2: Install Cypress GitHub App and Enable Integration for the Project

Follow the steps mentioned earlier to install the Cypress GitHub App at both the organization and project levels.

Step 3: Configure Status Checks and Pull Request Comments

Create a cypress.json file in your project's root directory with the required configuration:

{
"env": {
"CYPRESS_GITHUB_TOKEN": "<your-github-token>"
},
"integrationFolder": "integration",
"video": false,
"screenshotsFolder": "screenshots",
"reporter": "mochawesome",
"reporterOptions": {
"reportDir": "reports/mocha",
"overwrite": false,
"html": true
},
"baseUrl": "http://localhost:3000",
"videoUploadOnPasses": false,
"viewportWidth": 1280,
"viewportHeight": 720,
"specPattern": "integration/**/*.js"
}

Replace `` with your GitHub personal access token.

Step 4: Write Test Cases and Set Up GitHub Actions

Create a new integration file in the integration folder (e.g., example_spec.js) and write some test cases for your web application. You can find examples in the Cypress Example KitchenSink repository.

Set up GitHub Actions to run your tests as part of your CI pipeline by creating a .github/workflows/ci.yml file in your project's root directory:

name: Cypress Testing
on: [push, pull_request]
jobs:
test:
name: Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Node.js
uses: actions/setup-node@v2
with:
node-version: 14
- name: Install Dependencies
run: npm install
- name: Run Cypress Tests
run: npm run cypress:run

Step 5: Push Changes and Observe GitHub Integration

Commit your changes, push them to the repository, and observe the status checks and pull request comments on GitHub.

Common Mistakes

  1. Forgetting to add the Cypress GitHub App: Make sure you have installed the Cypress GitHub App for both your organization and the specific project.
  2. Incorrect GitHub personal access token: Ensure that you use a valid GitHub personal access token with the appropriate permissions (repo, write:discussion).
  3. Misconfigured webhook: Verify that the payload URL, trigger event, and content type are correctly configured in your repository's webhook settings.
  4. Incorrect Cypress configuration: Make sure you have added the necessary environment variables, specified the correct base URL, and set up the reporter options as required.
  5. Broken tests: Double-check that your test cases are written correctly and free of logical errors or syntax issues.
  6. Ignoring flaky tests: Flaky tests can lead to false positives and negatives in your test suite. Use tools like Garden to identify and address flaky tests.
  7. Neglecting test maintenance: Regularly review and update your test suite to ensure it remains relevant, accurate, and efficient.
  8. Overlooking test performance: Optimize your test suite for better performance by using techniques like parallel test execution, test isolation, and test data management.
  9. Ignoring test results: Analyze test results to identify trends, patterns, and areas for improvement in your application and testing strategy.
  10. Not integrating with other tools: use the power of GitHub Enterprise by integrating it with other tools like Slack, Jira, or Trello to enhance your workflow and collaboration.

Practice Questions

  1. How can I configure my Cypress project to use a custom GitHub personal access token?
  2. What should be the format of the payload URL for a GitHub webhook in the Cypress GitHub App integration?
  3. Why is it essential to set up status checks and pull request comments when integrating Cypress with GitHub Enterprise?
  4. How can I troubleshoot GitHub integration issues with my CI setup?
  5. What are some best practices for writing test cases using Cypress?
  6. How can I identify and address flaky tests in my Cypress test suite?
  7. What tools can I use to optimize the performance of my Cypress test suite?
  8. How can I integrate Cypress with other tools like Slack, Jira, or Trello?
  9. How can I ensure that my test suite remains relevant and accurate over time?
  10. What are some strategies for maintaining a scalable and efficient test automation workflow using GitHub Enterprise and Cypress?

FAQ

  1. Do I need to install the Cypress GitHub App for each repository individually, or can it be installed at the organization level?

The Cypress GitHub App should be installed at the organization level. Once installed, you can enable integration for specific repositories by adding a webhook.

  1. What are some common causes of flaky tests in Cypress, and how can I address them?

Flaky tests can be caused by race conditions, unpredictable network behavior, or test setup/

Cypress GitHub Enterprise app installation process (Test Automation) | Test Automation | XQA Learn