Configuring your CI for the GitHub integration

Once you have enabled Github integration, you need to set up your CI to configure the Eyes SDK with information related to the GitHub pull request or commit request. To allow the Eyes Batch to integrate data received from the GitHub server, you need to set the following Environment variables:

  • APPLITOOLS_API_KEY - Your API key. See How to obtain your API key.

  • APPLITOOLS_BATCH_ID - The GitHub commit SHA of the current build. This also must be set as an environment variable before running Eyes tests.

    • For a Pull request, the SHA value must be the last commit in the source branch.

    • For a Push action, the SHA value must be the last commit in the branch that was pushed.

If Eyes cannot recognize the End of Build event, (for example in your CI system, GitHub cannot recognize identify an End of Build event, or you have multiple concurrent builds), you also need to add a cURL command to notify Eyes when all builds are complete. For details, see Notifying Eyes when a build is complete.

Below are procedures to set required variables and other required settings in common CIs.

GitHub Actions

  • In the workflow YAML file, add the following:

    Copy 
    env:
        APPLITOOLS_API_KEY: ${{ secrets.APPLITOOLS_API_KEY }}
        APPLITOOLS_BATCH_ID: ${{ github.event.pull_request.head.sha || github.sha }}

    • The example above assumes that you have access to the GitHub secrets service and have stored your Applitools API key in the GitHub secret name APPLITOOLS_API_KEY.

      To obtain your API key, see How to obtain your API key.

    • The APPLITOOLS_BATCH_ID value is the Git Commit Id (SHA).

    • If you use the public cloud, the value of APPLITOOLS_SERVER_URL is 'https://eyesapi.applitools.com'.

      If you run the Eyes server on a private cloud or on-premise system, then change the value assigned to the environment variable APPLITOOLS_SERVER_URL to the URL of your Eyes server.

  • If your GitHub workflow includes two or more concurrent Eyes jobs, add another dependent job that waits for these jobs to complete and notifies Eyes that the batch has completed. For example, if you have three jobs called runtests1, runtests2, runtests3, add the following job to the YAML file:

    Copy 
    batch-completion-notification:
      # this runs after all the test jobs have completed
      needs: [runtests1, runtests2, runtests3]
      runs-on: ubuntu-latest
      steps:
        - name: Update Applitools batch status
          uses: wei/curl@v1.1.1
          with:
          args: -X POST -d -H "accept:*/*" https://eyesapi.applitools.com/api/externals/github/servers/github.com/commit/${{env.APPLITOOLS_BATCH_ID}}/complete?apiKey=${{env.APPLITOOLS_API_KEY}}

    See Notifying Eyes when a build is complete for details.

Travis CI

  • In the travis.yml file, add the following line to the script section that runs before an Eyes test runs:

    Copy 
    script:
    - export APPLITOOLS_BATCH_ID=$(echo ${TRAVIS_PULL_REQUEST_SHA:=$TRAVIS_COMMIT})

  • On your project page click on More options and then select Settings.

  • In the Environment Variables section, enter the following:

    • In the Name field enter APPLITOOLS_API_KEY.

    • In the Value field enter the value of your API key. To obtain the value of your API key, see How to obtain your API key.

  • Click Add.

CircleCI

  • In the config.yml file in the .circlec folder, add the following command under jobs/build/steps so that it runs before the Eyes test starts:

    Copy 
    jobs:
      build:
        steps:
           - run: 
               command: |
                  export APPLITOOLS_BATCH_ID=$(echo $CIRCLE_SHA1)
                  run_the_test

  • In the project dashboard, click the gear icon.

  • On the menu on the left, under Build Settings, click Environment Variables.

  • Click Add Variable.

  • In the Name field enter APPLITOOLS_API_KEY.

  • In the Value field enter the value of your API key. To obtain the value of your API key, see How to obtain your API key.

  • Click Add Variable.

Semaphore CI

  • On the Project page, click Project Settings.

  • In the setup panel, click Add New Command Line, then copy the following line to the field and press enter:

    Copy 
    export APPLITOOLS_BATCH_ID=$(echo $REVISION)

  • Click on Environment Variables and click Add.

  • In the Name field, enter APPLITOOLS_API_KEY.

  • In the Content field, enter the value of your API key. To obtain the value of your API key, see How to obtain your API key.

  • Select the Encrypt Content check box.

  • Click Create Variable.

AppVeyor

  • In the appveyor.yml file, add the following line in the init section:

    Copy 
    init:
      -ps: $env: APPLITOOLS_BATCH_ID =
      if ($env: APPVEYOR_PULL_REQUEST_HEAD_COMMIT) {
        $env: APPVEYOR_PULL_REQUEST_HEAD_COMMIT
      }
    else {
      $env: APPVEYOR_REPO_COMMIT
    }

  • On your project page, click SETTINGS.
  • On the left panel select Environment. and in the Environment Variables section click Add Variable.
  • In the Name field, enter APPLITOOLS_API_KEY.
  • In the Value field enter the value of your API key. To obtain the value of your API key, see How to obtain your API key.
  • Click Save.

Jenkins

Navigate to the Jenkins project configuration, go to the Execute shell window and enter the following:

Copy 
export APPLITOOLS_BATCH_ID=$(echo ${GIT_COMMIT})
export APPLITOOLS_API_KEY= "your api key"

For full instructions on integration with Jenkins, see Updating Jenkins build status.

Preparing your code for a commit push action

You need to add an API call to the CI script that will inform Applitools each time there is a commit push action.

Copy 
curl -L -d '' -X POST "$APPLITOOLS_SERVER_URL/api/externals/github/push?
apiKey=$APPLITOOLS_API_KEY&CommitSha=$APPLITOOLS_BATCH_ID&BranchName=<Branch name>
&ParentBranchName=<Parent branch name>"

  • <Branch name> represents the full GitHub branch name, including the organization, the repository, and the branch in the format my-org/my-repo/my-branch.

    Examples (Click to expand):
    Copy 
    curl -L -d '' -X POST "$APPLITOOLS_SERVER_URL/api/externals/github/push?
    apiKey=$APPLITOOLS_API_KEY&CommitSha=$APPLITOOLS_BATCH_ID&BranchName=${CIRCLE_PROJECT_USERNAME}/${CIRCLE_PROJECT_REPONAME}/${CIRCLE_BRANCH}
    &ParentBranchName=<Parent branch name - optional>"

    Copy 
    curl -L -d '' -X POST "$APPLITOOLS_SERVER_URL/api/externals/github/push?
    apiKey=$APPLITOOLS_API_KEY&CommitSha=$APPLITOOLS_BATCH_ID&BranchName=${GITHUB_REPOSITORY}/${GITHUB_REF_NAME}
    &ParentBranchName=<Parent branch name - optional>"

    Copy 
    #for private clouds, the address includes the cloud name; e.g, for MyOrgeyes.applitools.com, the server URL is MyOrgeyesapi.applitools.com
    export APPLITOOLS_SERVER_URL=https://eyesapi.applitools.com 

    curl -v -X DELETE "$APPLITOOLS_SERVER_URL/api/sessions/batches/$APPLITOOLS_BATCH_ID/close/bypointerid?apiKey=$APPLITOOLS_API_KEY" 

    Copy 
    $Env:APPLITOOLS_API_KEY = 'https://eyesapi.applitools.com'

    Copy 
    set APPLITOOLS_SERVER_URL=https://eyesapi.applitools.com

  • <Parent branch name> is optional. The default is the master branch of the repository.

  • The APPLITOOLS_API_KEY argument must be passed in the query and cannot be passed in the body.

  • <APPLITOOLS_BATCH_ID> is the GitHub commit SHA of the current build.