PR Testing for Mobile Apps

Native mobile pull requests do not produce a preview URL. QA.tech tests the binary your CI built for that PR, not a deployed website. After the upload, pin the run or change review to that build with applicationBuildShortId. If the GitHub App auto-runs without a build override, it uses the application’s default environment (the last configured staging or production build). That is not the PR binary.

Choose an integration mode

Mode	What runs	When to use
Test plan (API-driven)	A plan you already maintain (smoke, regression)	Deployment gates, required checks, known coverage
Change review (AI exploratory)	The same review agent as the GitHub App: selects relevant tests, fills gaps, posts a native PR/MR review	You want AI to decide what to test from the diff

Both modes use the same upload. They differ only in how you start testing after you have a build short ID.

Create the mobile application in Settings → Applications & Envs before CI uploads. See Mobile App Testing. Passing applicationBuildShortId creates or reuses an environment for that build; you do not add a new environment in the UI for every PR.

Prerequisites

Mobile testing enabled for the organization (contact support if it is not)
A mobile application in Settings → Applications & Envs (note the short ID, for example app_gXeBl2)
A test plan short ID for API-driven runs, or the GitHub App / GitLab MR integration connected for change reviews
An API token from Organization Settings → API Keys, stored as QATECH_API_TOKEN (GitHub) or QA_TECH_API_TOKEN (GitLab)
A simulator or emulator build in CI: Android .apk, or iOS .app compressed as .zip or .tar.gz. Device and App Store .ipa files cannot run on simulators. See Preparing Your App Build.

How it works

PR opened or updated
  → CI builds the app (simulator APK or zipped .app)
  → CI uploads the file (presigned URL, then create build)
  → CI starts a test plan or change review pinned to applicationBuildShortId
  → QA.tech creates or reuses an environment for that exact build
  → Tests run on a cloud simulator or emulator

See the Application Builds API for request and response details.

Upload the PR build

Run this after your compile step, on every PR. Replace app_gXeBl2 and the file path.

APP_ID="app_gXeBl2"
BUILD_FILE="app/build/outputs/apk/debug/app-debug.apk"
FILE_NAME=$(basename "$BUILD_FILE")

UPLOAD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds/upload-url" \
  -H "Authorization: Bearer $QATECH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"fileName\": \"$FILE_NAME\"}")
UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
BUILD_TOKEN=$(echo "$UPLOAD_RESPONSE" | jq -r '.buildToken')

curl -sSf -X PUT "$UPLOAD_URL" \
  --upload-file "$BUILD_FILE" \
  -H "Content-Type: application/octet-stream"

BUILD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds" \
  -H "Authorization: Bearer $QATECH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"platform\": \"android\", \"buildToken\": \"$BUILD_TOKEN\"}")
BUILD_SHORT_ID=$(echo "$BUILD_RESPONSE" | jq -r '.applicationBuildShortId')
echo "Uploaded $BUILD_SHORT_ID"

For iOS, zip the .app first, set "platform": "ios", and upload the archive:

zip -r AppName.zip AppName.app
BUILD_FILE="$PWD/AppName.zip"

The presigned URL expires in about two hours. Maximum file size is 4 GB. To install companion apps on the same device, upload those builds too and pass their short IDs in otherApplicationBuildShortIds. See Other Apps.

Set up GitHub Actions

Store QATECH_API_TOKEN under Settings → Secrets and variables → Actions.

Run a test plan on the PR

Use this when a required check should run a known plan against the PR binary.

name: QA.tech mobile PR tests
on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build APK
        run: ./gradlew assembleDebug

      - name: Upload build to QA.tech
        id: upload
        env:
          QATECH_API_TOKEN: ${{ secrets.QATECH_API_TOKEN }}
          APK_PATH: app/build/outputs/apk/debug/app-debug.apk
        run: |
          APP_ID="app_gXeBl2"
          FILE_NAME=$(basename "$APK_PATH")
          UPLOAD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds/upload-url" \
            -H "Authorization: Bearer $QATECH_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"fileName\": \"$FILE_NAME\"}")
          UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
          BUILD_TOKEN=$(echo "$UPLOAD_RESPONSE" | jq -r '.buildToken')
          curl -sSf -X PUT "$UPLOAD_URL" \
            --upload-file "$APK_PATH" \
            -H "Content-Type: application/octet-stream"
          BUILD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds" \
            -H "Authorization: Bearer $QATECH_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"platform\": \"android\", \"buildToken\": \"$BUILD_TOKEN\"}")
          echo "build_short_id=$(echo "$BUILD_RESPONSE" | jq -r '.applicationBuildShortId')" >> "$GITHUB_OUTPUT"

      - uses: QAdottech/run-action@v3
        with:
          api_token: ${{ secrets.QATECH_API_TOKEN }}
          test_plan_short_id: 'pln_abc123'
          blocking: true
          applications_config: |
            {
              "applications": {
                "app_gXeBl2": {
                  "environment": {
                    "applicationBuildShortId": "${{ steps.upload.outputs.build_short_id }}"
                  }
                }
              }
            }

Replace app_gXeBl2, pln_abc123, and the APK path. Set blocking: true if the workflow should fail when tests fail. iOS builds need a macOS runner and a simulator .app. Zip it, use "platform": "ios", and point BUILD_FILE at the archive. Full xcodebuild flags are in Mobile App Testing.

Run a change review on the PR

Use this when you want the review agent to select tests from the diff and post a native GitHub review. Install the GitHub App at the organization level with access to the repository. Turn off Auto-run on PRs for that repo in Settings → Integrations → GitHub App so QA.tech does not also start a review against the default environment.

name: QA.tech mobile change review
on:
  pull_request:

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build APK
        run: ./gradlew assembleDebug

      - name: Upload build to QA.tech
        id: upload
        env:
          QATECH_API_TOKEN: ${{ secrets.QATECH_API_TOKEN }}
          APK_PATH: app/build/outputs/apk/debug/app-debug.apk
        run: |
          APP_ID="app_gXeBl2"
          FILE_NAME=$(basename "$APK_PATH")
          UPLOAD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds/upload-url" \
            -H "Authorization: Bearer $QATECH_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"fileName\": \"$FILE_NAME\"}")
          UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
          BUILD_TOKEN=$(echo "$UPLOAD_RESPONSE" | jq -r '.buildToken')
          curl -sSf -X PUT "$UPLOAD_URL" \
            --upload-file "$APK_PATH" \
            -H "Content-Type: application/octet-stream"
          BUILD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds" \
            -H "Authorization: Bearer $QATECH_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"platform\": \"android\", \"buildToken\": \"$BUILD_TOKEN\"}")
          echo "build_short_id=$(echo "$BUILD_RESPONSE" | jq -r '.applicationBuildShortId')" >> "$GITHUB_OUTPUT"

      - uses: QAdottech/run-action/change-review@v3
        with:
          api_token: ${{ secrets.QATECH_API_TOKEN }}
          applications_config: |
            {
              "applications": {
                "app_gXeBl2": {
                  "environment": {
                    "applicationBuildShortId": "${{ steps.upload.outputs.build_short_id }}"
                  }
                }
              }
            }

The Change Review Action reads the PR URL from github.event.pull_request.html_url on pull_request events. Set blocking: true if the job should wait for the verdict. Inputs and outputs are in Change Review Action. Write a PR description that names the user-facing flows to test. The agent uses that context the same way it does for web PRs. See PR Testing.

Set up GitLab CI

Store QA_TECH_API_TOKEN as a CI/CD variable. Upload the build, then start a run or a change review. Change reviews need the repository connected under Settings → Integrations → GitLab.

qatech_mobile_mr:
  stage: test
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script: |
    APP_ID="app_gXeBl2"
    BUILD_FILE="app/build/outputs/apk/debug/app-debug.apk"
    FILE_NAME=$(basename "$BUILD_FILE")

    UPLOAD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds/upload-url" \
      -H "Authorization: Bearer $QA_TECH_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"fileName\": \"$FILE_NAME\"}")
    UPLOAD_URL=$(echo "$UPLOAD_RESPONSE" | jq -r '.uploadUrl')
    BUILD_TOKEN=$(echo "$UPLOAD_RESPONSE" | jq -r '.buildToken')
    curl -sSf -X PUT "$UPLOAD_URL" \
      --upload-file "$BUILD_FILE" \
      -H "Content-Type: application/octet-stream"
    BUILD_RESPONSE=$(curl -sSf -X POST "https://api.qa.tech/v1/applications/$APP_ID/builds" \
      -H "Authorization: Bearer $QA_TECH_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"platform\": \"android\", \"buildToken\": \"$BUILD_TOKEN\"}")
    BUILD_SHORT_ID=$(echo "$BUILD_RESPONSE" | jq -r '.applicationBuildShortId')

    MR_URL="${CI_MERGE_REQUEST_PROJECT_URL}/-/merge_requests/${CI_MERGE_REQUEST_IID}"
    curl -sSf -X POST "https://api.qa.tech/v1/chat/change-review" \
      -H "Authorization: Bearer $QA_TECH_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{
        \"mode\": \"pr\",
        \"prUrl\": \"$MR_URL\",
        \"vcsProviderId\": \"gitlab\",
        \"applicationOverrides\": [{
          \"applicationShortId\": \"$APP_ID\",
          \"environment\": { \"applicationBuildShortId\": \"$BUILD_SHORT_ID\" }
        }]
      }"

To run a fixed plan instead of a change review, call Start Run with testPlanShortId and the same applications override. Poll Get Run if the job should fail on test failure.

Set up Bitrise

Bitrise is the same upload-then-run sequence, using $BITRISE_APK_PATH or a zipped simulator .app from xcode-build-for-simulator. The Bitrise page has copy-paste script steps for Android and iOS, including blocking (poll until the run finishes). To post an MR/PR review instead of only starting a plan, keep that upload script and replace the final POST /v1/run with POST /v1/chat/change-review and applicationBuildShortId, as in the GitLab example.

Network access

Mobile sessions use a different outbound IP pool than web tests. If the app talks to a firewalled backend, allowlist the ranges under Settings → Network (Mobile Testing IP Whitelist). See Network Access.

Troubleshooting

Tests ran, but against the old app The job did not pass applicationBuildShortId, or GitHub App Auto-run on PRs started a second review on the default environment. Pin the CI trigger to the uploaded build and turn auto-run off when CI owns the review. Upload or create-build fails for iOS The file is a device or App Store .ipa. Produce a simulator .app and upload a .zip or .tar.gz. See Preparing Your App Build. Change review starts but never comments on the PR The GitHub App is not installed, or it does not have access to the repository. The Change Review Action still needs that App connection so the agent can read the PR and post the review. See Change Review Action setup. Login or API calls fail in the emulator The backend is blocking mobile testing IPs. Update the Mobile Testing IP Whitelist.

Mobile App Testing - Application setup, simulator builds, device presets
Application Builds API - Upload URL, create build, list builds
GitHub Actions - Test Run Action and Change Review Action reference
GitHub App - Automatic PR reviews (web preview URLs)
Bitrise - Mobile CI upload and test plan trigger
CI/CD Integration - API-driven vs AI exploratory modes
PR Testing - PR descriptions and review context

Get Started

Core Concepts

Configuration

Best Practices

Test Features

Integrations

Applications

CLI

PR Testing for Mobile Apps

Choose an integration mode

Prerequisites

How it works

Upload the PR build

Set up GitHub Actions

Run a test plan on the PR

Run a change review on the PR

Set up GitLab CI

Set up Bitrise

Network access

Troubleshooting

​Choose an integration mode

​Prerequisites

​How it works

​Upload the PR build

​Set up GitHub Actions

​Run a test plan on the PR

​Run a change review on the PR

​Set up GitLab CI

​Set up Bitrise

​Network access

​Troubleshooting

​Related documentation

Choose an integration mode

Prerequisites

How it works

Upload the PR build

Set up GitHub Actions

Run a test plan on the PR

Run a change review on the PR

Set up GitLab CI

Set up Bitrise

Network access

Troubleshooting

Related documentation