Skip to main content

​
Overview: When to use GitHub Actions

This guide is for teams that use GitHub Actions as their CI system and want a simple, declarative way to upload mobile builds and trigger test runs without writing custom scripts. Use GitHub Actions if your repository already builds mobile artifacts in a GitHub Actions workflow and you prefer using prebuilt actions over maintaining Node.js scripts or Fastlane lanes. This guide assumes your mobile builds already run in GitHub Actions and produce a build artifact.
Before using GitHub Actions:
  1. Make sure your GitHub Actions workflow produces a mobile build artifact (APK, AAB, or IPA)
  2. A QA Wolf API key is stored as a GitHub secret (QAWOLF_API_KEY)
  3. Artifact naming conventions are defined for your environments
Mobile triggers must be enabled for your workspace by QA Wolf before test runs will execute.

​
How the GitHub Actions integration works

The GitHub Actions integration uses two QA Wolf-provided actions:
1
Uploading a mobile build artifact to QA Wolf
2
Notifying QA Wolf of a deployment event to trigger a test run
You can upload builds without triggering runs, which is useful during initial setup or validation.
You provide the artifact basename when uploading. QA Wolf applies the file extension automatically based on the uploaded file.

​
How to add QA Wolf actions to your workflow

Add the QA Wolf actions to an existing GitHub Actions workflow that builds your mobile app. The workflow must run after the build artifact has been created. Make sure the workflow has access to the QAWOLF_API_KEY secret.

​
To add the QAWOLF_API_KEY secret:

1
Open your GitHub repository and go to Settings.
2
Select Secrets and variables → Actions.
3
Add a new repository secret named QAWOLF_API_KEY and paste your API key.

​
To find the QAWOLF_API_KEY:

1
Open the Workspace name dropdown in QA Wolf and click Workspace Settings.
2
Choose Integrations,
3
Generate your QAWOLF_API_KEY by clicking the icon to the right of API Key under API Access.

​
How to upload a mobile build artifact

After your workflow produces a mobile build artifact, upload it to QA Wolf using the upload action. 
- name: Upload mobile build to QA Wolf
  id: upload-run-input
  uses: qawolf/upload-run-inputs-executable-action@v1
  with:
    qawolf-api-key: ${{ secrets.QAWOLF_API_KEY }}
    input-file-path: ./path/to/build.apk
    executable-file-basename: app-staging
If this step completes successfully, the artifact is uploaded and available for test runs. 
name: Deploy and Notify QA Wolf
on: pull_request
jobs:
  ...
  notify:
    needs: deploy-preview-environmnent
    name: Trigger QA Wolf PR testing
    runs-on: ubuntu-latest
    steps:
    ...
      # Upload the run input file
      - name: Upload Run Input
        id: upload-run-inputs-executable
        uses: qawolf/upload-run-inputs-executable-action@v1
        with:
          qawolf-api-key: "${{ secrets.QAWOLF_API_KEY }}"
          input-file-path: "path/to/file.apk"
      - name: Notify QA Wolf of deployment
        uses: qawolf/notify-qawolf-on-deploy-action@v1
        env:
          ...
          # Use the output in the RUN_INPUT_PATH environmental variable
          RUN_INPUT_PATH: "${{ steps.upload-run-inputs-executable.outputs.destination-file-path }}"
          ...
        with: ...

​
How to trigger a test run

After uploading the artifact, notify QA Wolf that a new deployment is ready for testing. 
- name: Notify QA Wolf of deployment
  uses: qawolf/notify-qawolf-on-deploy-action@v1
  with:
    qawolf-api-key: ${{ secrets.QAWOLF_API_KEY }}
    deployment-type: android_app
    variables: >
      { "ANDROID_APP": "/home/wolf/run-inputs-executables/${{ steps.upload-run-input.outputs.destination-file-path }}" }
The deployment type and environment key must match the values configured by QA Wolf for your workspace.
If mobile triggers have not yet been enabled, this step will complete without starting a test run.

​
How to verify the integration

1
Run the GitHub Actions workflow
2
Verify that the artifact upload step completes successfully
3
Confirm that the deployment notification step runs without errors
4
Once mobile triggers are enabled, check the Runs tab for the triggered test run

​
Troubleshooting and common issues

  • If uploads succeed but no runs start: Mobile triggers may not yet be enabled. Contact QA Wolf to complete platform configuration
  • If the artifact is not found during execution: Verify that the artifact basename matches your naming conventions and that the destination file path from the upload step is used to trigger the run.
  • If you see authentication errors: Verify that QAWOLF_API_KEY is configured correctly as a GitHub Actions secret.
  • If the workflow fails before the QA Wolf steps run: Verify that the mobile build step completes successfully and produces the expected artifact.
Last modified on March 2, 2026