Using the Applitools Bitbucket proxy service

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

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

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

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

The Applitools Bitbucket proxy service.

Applitools provides the proxy service for customers that can't provide Eyes with direct HTTPS access to the Bitbucket server. The proxy service runs on the same network as the Bitbucket 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 Bitbucket 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 Bitbucket server with status information. When Eyes indicates that it has a status update, the proxy service obtains the information and updates the Bitbucket server on behalf of the Eyes server.

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 Using the Applitools Bitbucket proxy service

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 the proxy service

Configuration prerequisites

To run the proxy service you need the following:

PrepareNotes
The API key of an Eyes user with team admin rights See How to obtain your API key
Your SCM server URL 
The personal access token (PAT) that provides access to Bitbucket with read admin rights.Obtain this from Bitbucket.

The names of the repositories that you want to provide Eyes access to.

You will select the required repositories from the list of available repositories displayed by the proxy service.

Running and configuring the server

Starting the proxy service

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 which repositories you want to allow Eyes access to and provide the necessary Eyes and SCM credentials. You do this by starting the proxy service and the accessing it with a browser.

  1. Make sure the proxy service is running, as described in Running and configuring the server.

    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 which source control management system you want to integrate with. In this case select Bitbucket.

  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. The next screen displays any SCM servers that have already been configured. If the server you want to configure appears in the list then click on it, otherwise click Add a new server, enter the URL in the text field that displays, click Save and then click on the newly added server.

  5. The first time you interact with the server, no repositories will have been enabled for Eyes access, so you will see the following screen - click Manage Repositories to select the repositories that you want to enable Eyes access to.

  6. You will now see a screen with a list of all the repositories on the SCM server. The first time you configure the proxy service all the repositories will be in the disabled state i.e. grayed out in the left position:

  7. Click on the toggle next to the repository that you want Eyes to access, to provide the a Personal access token (PAT) for repos that are disabled, or to change the PAT for repos that are already enabled. You will then see a screen asking you to enter the Personal access token for that repository. Obtain the PAT value from the SCM system, paste it into the text box and then click on Save.

  8. If the PAT is valid the repository you selected will now be in the enabled state. You can now proceed to enable any other repositories that you want to allow Eyes to access, and then exit from the browser.

Changing the configuration

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