Using the Applitools GitHub proxy service

Overview

Eyes/GitHub integration requires two ways communication between the Eyes server and the GitHub server.

Communication from the Eyes server to the GitHub server is required during the setup phase when you select repositories to integrate with. The Eyes server utilizes the GitHub API to generate webhooks in the selected repositories, which send all the pertinent GitHub events to Eyes. Additionally, the GitHub API is used to update the status when an Eyes batch is completed, ensuring that the status needs to be updated on the corresponding GitHub commit or pull request.

Communication from the GitHub server to the Eyes server is necessary when the webhooks send events to the Eyes server.

If your GitHub server is protected by a firewall and you are unable to add a custom rule to expose the necessary GitHub APIs for Eyes to call them, you can utilize the Eyes-scm application. With Eyes-scm, webhooks can be created on the relevant GitHub repositories. This approach ensures that the Eyes server never directly calls the GitHub APIs, as all calls are made through the application.

To utilize Eyes-scm, you will need to set up integration and select the required repository within the Eyes-scm interface, rather than in the Eyes server admin dashboard.

Once integration is complete, the process of updating the commit or pull request status is also handled by Eyes-scm. The Eyes-scm application continuously polls the Eyes server for status update commands and updates the status on the GitHub server when necessary.

Using the Applitools GitHub proxy service requires the following steps:

  1. Create the GitHub App for the Eyes integration – The Eyes GitHub integration requires that a GitHub App with the necessary permissions is created in your GitHub account.

  2. Install the GitHub App – This is done on the GitHub server.

  3. Install the proxy service – This is done on a server in your organization that has HTTPS access to the GitHub server.

Creating the GitHub App for the Eyes integration

A GitHub App is an entity created and stored on the GitHub server, responsible for defining access permissions for third-party tools. The integration between Applitools Eyes and GitHub requires a GitHub App. This GitHub App enables the receipt of pull and push request events and facilitates the updating of status information on the repositories where the executed test code runs.

  1. On the GitHub server that stores your repositories, click on the option to create a GitHub App.

    We recommend you name the app Applitools Eyes Integration, so that other teams in your organization can easily find the app and use it as well.

  2. Enable the Webhook option.

  3. Set the Webhook URL to:

    https://<My_Org>.applitools.com/api/externals/github/v2/events?orgId=<orgId>&serverId=<GitHub server host>

    where <My_Org> is the name of your Eyes server. This is the value that is typically assigned to the environment variable APPLITOOLS_SERVER_URL, or is passed in the test code to the method configuration.setServerUrl or eyes.setServerUrl.

  4. In the Webhook secret field, enter the text you want to use as the secret. Save this text, you will need it later when configuring Eyes.

  5. In the Repository Permission section, set the following permissions:

    • Metadata - read only

    • Pull requests - read only

    • Commit statuses - read & write

  6. In the Subscribe to events section, select Pull request.

  7. Copy the value displayed in the App ID field. You will need this later when configuring Eyes.

  8. Click the Generate a private key button. This downloads a file with a .pem suffix. You will need the contents of the file later when configuring Eyes.

Installing the GitHub App

After creating the GitHub App, you will need to install it on your GitHub account. For detailed instructions, for details see GitHub documentation.

All of the Eyes teams in your organization can share a GitHub App, or each team can create its own. The difference is only in the list of repositories configured for the GitHub App. The simplest scheme is that a single GitHub App provides access to all of the repositories used by all of the Eyes teams. Alternatively, each Eyes team can create its own GitHub App that provides Eyes with access to that team's repositories. If required, a team can connect to multiple GitHub organizations.

Installing the proxy service

The Applitools proxy service is a Node.js-based program that runs in the background, continually polling the Eyes server to see if it needs to update the GitHub server with status information. When Eyes indicates that it wants to update the status, the proxy service interacts with GitHub on behalf of Eyes.

Users need to complete a one-time configuration of the proxy service in order to provide access permission and other information that the service needs to implement the Eyes/GitHub interaction. This is done by accessing the proxy server using a browser.

Installation prerequisites

Before installing the proxy service, you must have:

  • Node.js installed (version 12 or later)

  • Yarn Installed

  • Information from the GitHub App creation:

    • Webhook secret

    • App ID

    • Content of the .pem file from the GitHub App installation.

  • The Eyes server URL, this is the URL that you use the open the Test Manager

  • Your Eyes organization ID, available in the Admin/Account page in the ID field.

One-time setup

Set up the following environment variables so that they are available to the proxy service.

Copy 
# set the Eyes server URL to your server
EYES_SERVER_URL=https://myOrg-eyes-api.applitools.com
#set the Eyes organization ID
EYES_ORG_ID=xx1234HxxXv987AB24q1vlF25BxxYaZ1234x5Hk3XaSa111
# set the HTTP port the proxy service should use (optional - default is 4000)
PORT=1234

To install the proxy server run the following from any command shell:

npm i -g @applitools/eyes-scm

Running and configuring the server

Use the following command to start the server:

eyes-scm

Configuring repositories and access credentials

The first time your run the server, you need to define the repositories you want to allow Eyes to access and provide the necessary Eyes and GitHub credentials. To do this, start the proxy service and then access it with a browser.

  1. Make sure the proxy service is running as described in One-time setup.

    Start a browser on the server where the proxy is running and navigate to the proxy service. The default URL is localhost:4000.

  2. Select Github as the source control management system.

  3. Enter an Eyes API key with Team Admin rights and full privileges. See How to retrieve your API key.

  4. Click Next.

  5. If this is your initial installation, click Add a new server.

    If you are reconfiguring an existing installation, then you will see a list of GitHub servers that are currently installed. Either select an existing server from the list or click Add a new server.

  6. Enter the URL of your GitHub server and the secret entered when the GitHub App was created.

  7. Click Save.

  8. In the list of servers, click on the server to configure it.

  9. On the first installation, no repositories will have been enabled, click Manage Repositories to select the repositories that you want Eyes to integrate with.

  10. On the first installation, as repositories have been enable the enter the GitHub App ID and the App private key (the entire contents of the downloaded .pem file) and then click Save.

  11. A screen with a list of all the repositories on the SCM server is displayed. The first time you configure the proxy service, all of the repositories are disabled (grayed out). Enable the repositories that you want Eyes to access.

    If there are a lot of repositories, you can use the Search option to identify the required repositories.

Disabling automated batch closing

By default, GitHub integration closes a batch automatically once the CI build operation is completed. You many need to disable automatically closing, for example if you have parallel push and pull requests, or run builds concurrently or you have builds that consists of multiple tests and you want all of the results to appear together in a single batch. If you disable automated batch closing, you need to close the batch explicitly when the build is complete in your CI.

To disable Automated batch closing, clear the checkbox for the that repository.

Once you have installed the GitHub App and proxy service, continue with Configuring GitHub repositories.