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

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

Enabling Applitools logs in GitHub Actions

To collect Applitools SDK logs from GitHub Actions, add a step that enables logging and archives the log directory even if the test step fails:

- run: npm test
  env:
    APPLITOOLS_SHOW_LOGS: 'true'
    APPLITOOLS_LOG_DIR: 'logs/'
- name: Archive Applitools Logs
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: applitools-logs
    path: logs/

note

If your GitHub Actions job runs inside Docker, setting APPLITOOLS_SHOW_LOGS and APPLITOOLS_LOG_DIR is not enough. The log files are written inside the container and can be lost when the container stops unless the log directory is mounted to the workspace.

Example Docker command:

docker run \
  -e APPLITOOLS_SHOW_LOGS=true \
  -e APPLITOOLS_LOG_DIR=/usr/src/app/logs \
  -v ${WORKSPACE}/applitools-logs:/usr/src/app/logs \
  your-image-name

Adjust ${WORKSPACE} to the workspace path used by your CI environment.

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