Integrate a mobile build with GitHub Actions

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 you begin

1. Make sure your GitHub Actions workflow produces a mobile build artifact (APK, AAB, or IPA).
2. Artifact naming conventions are defined for your environments. See Artifact naming conventions below.

Before mobile test runs can execute, QA Wolf must enable mobile triggers for your workspace. QA Wolf will handle this and may ask you for:

• Which environments you want to test.
• Whether PR testing is enabled.
• The artifact naming conventions you are using.
• The upload and trigger method you chose.

Until this step is complete, CI jobs can upload artifacts and send deployment notifications, but mobile test runs will not start automatically.

How GitHub Actions works with QA Wolf

The GitHub Actions integration uses two QA Wolf-provided actions:

1. Upload a mobile build artifact to QA Wolf.

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

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.

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.

   

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.

Artifact naming conventions

Mobile build artifacts must follow consistent naming conventions so QA Wolf can correctly associate each build with the right environment and make failures easier to diagnose.

The artifact name is used to identify:

• Which environment the build belongs to.
• Whether the build is tied to a pull request.
• Which build was used for a given test run.

Static environments

Static environments are long-lived environments such as staging or release environments.

Format

<prefix>-<environment-name>

Example

app-staging

Use the same basename every time a build is generated for the same environment.

PR (ephemeral) environments

PR environments are short-lived and tied to a specific pull request. These are only relevant if PR testing is enabled.

Format

<prefix>-<org>-<repo>-pr<number>

Example

app-myorg-myrepo-pr123

Including the organization, repository, and pull request number ensures each build can be traced back to the correct change and environment.

QA Wolf applies the file extension (.apk, .aab, or .ipa) automatically based on the uploaded artifact. You only need to provide the basename.

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

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: >
      { "RUN_INPUT_PATH": "/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.

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.