Using the 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/Test center where Eyes has permission to access the network. Setting up this method is described in the main Bitbucket integration article Getting started

  • Eyes/Bitbucket interaction using a proxy service. This method is used when direct access by Eyes to Bitbucket is not available. Describing this proxy and how to set it up is the subject of this article.

The Applitools Bitbucket proxy service.

Applitools provides the proxy service to customers that can't provide direct Eyes access to the Bitbucket server network. 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

Installation prerequisites

Before starting the install you need the following:

A copy of the Eyes proxy service. You can obtain the URL of the proxy service repository from your Eyes service representative.
Installed Node.js At least version 12
Installed Yarn  
Your Eyes server URL and Eyes organization ID

You can obtain these from your Eyes service representative, or simply open the Test manager, navigate to the Admin page and copy them from from the URL:

One time setup

Setup the following environment variables so that they are available to the proxy service (the values are taken from the example above - replace these with the values relevant to your Eyes installation):

# set the Eyes server URL to your server
#set the Eyes organization ID
# set the HTTP port the proxy service should use (optional - default is 4000)

In the root directory where you cloned the Eyes proxy service repository run the following command in a Bash shell:

yarn install && cd client && yarn install && yarn build && cd ..

Running the proxy service

Configuration prerequisites

To run the proxy service you need the following:

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 your SCM with read admin rights.Obtain this from your SCM tool.

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 in the root directory where you cloned the Eyes proxy service repository:

yarn start

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. The first screen will request your API key, enter the key and click on the Go button.

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

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

  5. 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:

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

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