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.

Azure DevOps

In Azure, select Pipelines and then click on the name of your pipeline.
Click Edit.
Click Variables and set the variable applitools.api.key with your API Key. To get the value of your API key, see How to retrieve your API key.

Add the following to the azure-pipelines.yml file:

Copy

variables:
  - name: commitSha
  # Use Build.SourceVersion if we aren't in a PR
    ${{ if ne(variables['Build.Reason'], 'PullRequest') }}:
     value: $(Build.SourceVersion)
  # Use System.PullRequest.SourceCommitId if we are in PR
    ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
     value: $(System.PullRequest.SourceCommitId)

 env:
   APPLITOOLS_API_KEY: $(applitools.api.key)
   APPLITOOLS_BATCH_ID: $(commitSha)

for example:

Copy

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml

trigger:
- master

pool:
  vmImage: ubuntu-latest
variables:
  - name: commitSha
  # Use Build.SourceVersion if we aren't in a PR
    ${{ if ne(variables['Build.Reason'], 'PullRequest') }}:
     value: $(Build.SourceVersion)
  # Use System.PullRequest.SourceCommitId if we are in PR
    ${{ if eq(variables['Build.Reason'], 'PullRequest') }}:
     value: $(System.PullRequest.SourceCommitId)

steps:
- script: echo Hello, world!
  displayName: 'Run a one-line script'

- script: |
  
  # Run Applitools visual tests here

  displayName: 'Run a multi-line script'
  env:
    APPLITOOLS_API_KEY: $(applitools.api.key)
    APPLITOOLS_BATCH_ID: $(commitSha)

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):

Circle CI:

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

GitHub Actions:

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

Linux or /Mac

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"

Windows (PowerShell)

Copy

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

Windows (Command Prompt)

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.