Using the Applitools GitHub proxy service

Overview

In order to use the Applitools GitHub proxy service, you need to take the following steps:

  1. Creating the GitHub App for the Eyes integration. The Eyes GitHub integration requires that a GitHub App with the necessary permissions is created on your GitHub account.

  2. Installing the GitHub App. This is done on the GitHub server.

  3. Installing 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 that defines the access permission for third-party tools. The Applitools Eyes/GitHub integration requires such a GitHub App so that it can receive pull and push request events and update status information on the repositories where the executed test code runs.

In this section, we describe the settings and permission Eyes needs when you create a GitHub App. For details on the procedure for creating and installing a GitHub App, see the GitHub documentation.

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

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

  3. Enable the Webhook option.

  4. Set the Webhook URL to https://myorgeyesapi.applitools.com/api/externals/github/v2/events?orgId=<orgId>&serverId=<GitHub server host>, where myorgeyesapi.applitools.com 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.

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

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

    • Metadata - readonly

    • Pull requests - readonly

    • Commit statuses - read & write

    1. 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

In the Using the Applitools GitHub proxy service section, we described the need to create a GitHub App that defines the permissions Eyes needs in order to interact with GitHub. Once the GitHub App exists, you need to install it on your GitHub account. The procedure for doing this is described in the 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.

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 At least version 12
Yarn Installed  
Information from the GitHub App creation

The Webhook secret, App ID and the content of the .pem file from the GitHub App installation. See Installing the GitHub App
Your Eyes server URL

Your Eyes server URL is the URL that you use the open the Test manager
Your Eyes organizition ID This can be found on 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. 

# set the Eyes server URL to your server
EYES_SERVER_URL=https://myOrganization.eyesapi.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

Start the server by running the following command:

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.

    Start a browser on the server where the proxy is running and navigate to it by entering the URL  localhost:4000. If you set a different port number, as described in One-time setup, then use the configured port number instead of the default 4000.

  2. Start off by selecting the source control management system that you want to integrate with. In this case, select GitHub.

  3. The next screen asks you to enter your Eyes API key. This must be a key with Team admin rights with full privileges. For instructions on how to create such a key or to get an existing API key, see The Admin API Keys view. Enter your Eyes API key, and click on the Next button.

  4. If this is your initial installation, then the next screen displays No services are configured. 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 on Add a new server.

  5. The dialog will change to allow you to enter the URL of your GitHub server and the secret entered when the GitHub App was created. Once you have entered these details, click Save.

  6. The dialog will change to show the newly added server. Click on the server to configure it.

  7. On the first installation, no repositories will have been enabled, so the dialog will display as follows. Click Manage Repositories to select the repositories that you want Eyes to integrate with.

  8. On the first installation, as repositories have been enable the dialog will ask you to enter the GitHub App ID and the App private key (the entire contents of the downloaded .pem file). Enter these details and click Save.

  9. 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 in a disabled state (i.e. grayed out with toggles in the left position). Click on the toggles to the left of the repositories that you want Eyes to access.

  10. By default, GitHub integration closes a batch automatically once the CI build operation is completed. If your build runs concurrently or consists of multiple test and you want all of the results to appear together in a single batch, you need to disable automatic closing of the batch and close the batch explicitly when the build is complete in your CI.

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

Changing the configuration

If you want to enable or remove access to repositories, or to change the Eyes API Key or the GitHub App, then open the browser to the proxy service, as described above, and make the necessary changes.

As part of the Eyes/GitHub integration, the Eyes server sends batch status information to the GitHub server. Applitools provides two different ways to implement this Eyes/GitHub interaction:

  • Eyes/GitHub HTTPS interaction. This is the recommended method when Eyes can directly interact with a GitHub cloud or on a on-premise GitHub server where Eyes has permission to access the network.

  • Eyes/GitHub interaction using a proxy service. This method is used when direct access by Eyes to GitHub is not available.

This article describes how to setup the proxy service. The setup when Eye can directly interact with GitHub is described in the article "github-integration.htm#Getting.

The Applitools GitHub proxy service.

Applitools provides the proxy service for customers that can't provide Eyes with direct HTTPS access to the GitHub server. The proxy service runs on the same network as the GitHub server, and has the following roles:

  • Provides a setup wizard that guides the user to provide the information required by the proxy service such as the GitHub server URL, the names of the repositories where Eyes tests are being run and the Personal access token required to access them. The user also provides the URL of the Eyes server and API Key.

  • Once the setup information has been provided, the proxy service 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 has a status update, the proxy service obtains the information and updates the GitHub server on behalf of the Eyes server.