Working With Github Actions

In most configurations, the SDK can automatically retrieve the APPLITOOLS_BATCH_ID and APPLITOOLS_BATCH_BUILD_ID information from Git. If the SDK cannot retrieve this information, you need to manually set up our 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.

• APPLITOOLS_BATCH_BUILD_ID - (optional) The GitHub build ID. This is required if you run multiple builds in parallel on the same commit SHA, for example, parallel push and PR builds of the same source branch. You can obtain the GitHub build ID from your CI, for example in GitHub Actions, access the build ID using the GITHUB_RUN_ID environment variable which contains the unique identifier for the current workflow run.

  If you run parallel push and pull requests, you need to disable Automatic Batch Closing, (see GitHub Proxy Service) and notify Eyes when a build is complete.

If Eyes cannot recognize the End of Build event, (for example, if your CI system or GitHub cannot 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.

Configuring the Applitools CI/CD Integration

1. In the workflow YAML file, add the following:

   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.

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

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

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

   If you use the optional APPLITOOLS_BATCH_BUILD_ID environment variable:

   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}}/${{env.APPLITOOLS_BATCH_BUILD_ID}}/complete?apiKey=${{env.APPLITOOLS_API_KEY}}

Preparing For Commit Push Action

If you're triggering a build from commit push actions, the Eyes server must be notified. Here's an example of how to notify the Eyes Server using a curl request:

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