Skip to main content
QA Wolf runs flows against a real build of your app: an .apk or .aab for Android, an .ipa for iOS. Your pipeline uploads each new build and reports it as a deployment, and a trigger you create starts the runs. Every run records which build it installed.

How it works

1

Upload the build

Your pipeline uploads the file to an environment. QA Wolf reads the app id, version and build number from it, and returns a build id.
2

Report the deployment

Your pipeline calls deployment.reportStatus with the build id in builds.
3

A trigger matches

The deployment’s first success report evaluates your triggers. Each one that matches creates a run, and the run installs the deployment’s builds.
4

The flow launches the build

launch({ app: { id } }) installs the run’s build of that app.
Uploading and reporting start nothing on their own. A workspace with no matching trigger records the deployment, runs nothing, and the pipeline step still succeeds. Create the trigger before you wire up the pipeline.

Requirements

  • An API key, created under Workspace Settings → API Keys. A workspace, organization or user key all work.
  • The workspace id, shown on the same page.
  • A QA Wolf environment to report into. The deploy resolves to an environment by alias or name, and a name that matches nothing creates a new environment that no trigger targets.
  • One of: the QA Wolf Fastlane plugin 1.2.0 or later, qawolf/upload-build-action@v1 with qawolf/notify-qawolf-on-deploy-action@v3 3.2.0 or later, or @qawolf/ci-sdk 3.5.0 or later.
  • @qawolf/flows 0.4.0 or later in your flows.
Upload builds lists every other way to upload a build, including the Builds page, the CLI and Tester chat.

Set up the pipeline

The plugin is not published to RubyGems, so point the Gemfile at the repository and pin a tag.
Run fastlane install_plugins, then add both actions to the lane that builds your app. upload_build_to_qawolf uploads the file that gradle or build_app built. notify_deploy_qawolf reports the deployment with every build the lane uploaded.
notify_deploy_qawolf reports a success status by default, which is the status that evaluates triggers. It sets QAWOLF_DEPLOYMENT_ID and QAWOLF_ENVIRONMENT_RUNS_URL in the lane context and the environment, and returns the deployment id. Runs start asynchronously afterwards, so no run id comes back.
A matrix over Android and iOS derives the same deployment identity for both legs, because no CI system exposes which leg is running. Reporting into one environment, the second leg starts nothing and the lane still goes green. Pass provider_deployment_discriminator on every job that deploys more than once at a time:
The plugin’s README lists every option, including pull request environments.
These examples upload an Android .apk. iOS works the same way: point the same steps at your .ipa, and name the service ios.

Create a trigger

A deployment starts nothing until a trigger matches it. Create one on the workspace’s triggers page, with conditions that match the deployments you now report: Shipping both platforms into one environment needs two triggers, one per servicePattern, each selecting that platform’s flows. Without the service condition both triggers fire on every deployment, so a new Android build also reruns the iOS flows on the environment’s last iOS build. deployTargetPattern matches on the deploy target URL, which a mobile build has none of, so it is not a way to tell builds apart. See Trigger fields for every condition and for the action that selects which flows run.
You can create and manage triggers from your own coding agent instead of the triggers page. Add the QA Wolf MCP and ask it to set up the triggers for your mobile environments. It can also list recent deployments and show why a trigger did or did not fire.

Use the build in a flow

Name the app by its Android package name or iOS bundle id:
The flow installs the run’s build of that app: the deployment’s build, or else the environment’s latest. Scheduled runs and runs started by hand install the environment’s latest build, so they test the last upload too. See How a run picks its build.

Verify the integration

1

Run the pipeline

Run the CI job that builds your app.
2

Check the upload and the report

The upload step prints the build id. The report step logs the deployment id and the environment’s runs page.
3

Check the trigger fired

Open the deployment in QA Wolf. It lists a verdict for every trigger, including the reason a trigger did not match. See Deployments.
4

Check the run used the build

Open the run the trigger created. It shows the app version it tested, which matches the build you just uploaded.

Troubleshooting

  • The upload is refused — the file is not an .apk, .aab or .ipa, or is over 1 GB. If your pipeline zips the app, upload the file inside the zip.
  • The build uploads, the deployment is recorded, and nothing runs — no trigger matched. Open the deployment and read the per-trigger verdicts. The usual causes are an environment name that created a new environment instead of resolving an existing one, and a servicePattern on the trigger that the report does not send a service for.
  • Only one of the two platforms runs — both legs reported under the same providerDeploymentId, so the second updated the first deployment instead of creating one, and only a deployment’s first success report evaluates triggers. Give each leg its own identity: provider_deployment_discriminator on Fastlane, discriminator on detectProviderDeploymentId, deployment-id on the GitHub Action.
  • One platform’s build also reran the other platform’s flows — the triggers have no servicePattern, so both fire on every deployment. The other platform’s flows install that environment’s last build of their own platform.
  • launch fails with “No build of … on this environment” — the run has no build of that app. Check that the id in launch matches the build’s app id, and that the build was uploaded to this environment or reported with the deployment. A build whose file expired counts as absent.
  • The run installed an old file, or shows no app version — the flow calls launch() with no app, or with app: { path } or app: { env }, so it reads RUN_INPUT_PATH or a fixed file. Change it to launch({ app: { id } }). See Move from legacy uploads.
  • The pipeline step passes but the workspace never sees the deploy — the step is still on the legacy deploy webhook. @v1 and @v2 of the notify action, Fastlane plugin 0.4.8 and below, and the SDK’s attemptNotifyDeploy all report through it, and triggers never see it.
  • Authentication errors — check QAWOLF_API_KEY, and that workspaceId names the workspace the key may act on.
Last modified on November 4, 2026