> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile pull request testing

> Upload each pull request iOS or Android build and review that binary.

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 build stored on the application's default environment. That is not the PR binary. Scheduled runs and chats without an override use the same stored build, so [keep it on the latest merged build](#keep-the-environment-on-the-latest-merged-build).

## 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](https://docs.qa.tech/configuration/github-app.md): 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.

> [!NOTE]
>
> Create the mobile application in **Settings → Applications & Envs** before CI
> uploads. See [Mobile App Testing](https://docs.qa.tech/test-features/mobile-app-testing.md). 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](mailto:support@qa.tech) if it is not)
* A mobile application in **Settings → Applications & Envs**. Each row has a short ID (`app_…`). Use the three-dot menu → **Copy Short ID**. You do not need a test plan for this. **Test Plans → API Integration** only lists apps already on a plan.
* A [test plan](https://docs.qa.tech/core-concepts/test-plans.md) short ID for API-driven runs, **or** the [GitHub App](https://docs.qa.tech/configuration/github-app.md) / [GitLab MR integration](https://docs.qa.tech/configuration/gitlab.md) connected for change reviews
* An API token from **Organization Settings → API Keys**, stored as `QATECH_API_TOKEN` (GitHub) or `QA_TECH_API_TOKEN` (GitLab). Project-scoped keys are fine. Org-scoped keys need `projectShortId` on list and upload APIs.
* A project short ID for GitHub Actions (for example `proj_abc123`). Copy it from the project URL or Settings.
* 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](https://docs.qa.tech/test-features/mobile-app-testing.md#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](https://docs.qa.tech/api-reference/application-builds.md) for request and response details.

## Upload the PR build

CI uploads the binary after the compile step, then starts a test plan or change review pinned to `applicationBuildShortId`. The copy-paste upload script and change-review call live under [API pull request testing](https://docs.qa.tech/pr-testing/api.md#upload-the-pr-build). Bitrise paths (`$BITRISE_APK_PATH`, simulator `.app`) are on [Bitrise pull request testing](https://docs.qa.tech/pr-testing/bitrise.md#upload-the-build).

To install companion apps on the same device, upload those builds too and pass their short IDs in `otherApplicationBuildShortIds`. See [Other Apps](https://docs.qa.tech/test-features/mobile-app-testing.md#other-apps).

Per-CI steps for starting the review are on [GitHub](https://docs.qa.tech/pr-testing/github#mobile-build), [GitLab](https://docs.qa.tech/pr-testing/gitlab.md#mobile-build), [Bitrise](https://docs.qa.tech/pr-testing/bitrise.md#mobile-build), and [fastlane](https://docs.qa.tech/pr-testing/fastlane.md). To run a test plan against the same build, see [Mobile regression testing](https://docs.qa.tech/regression-testing/agents/mobile.md#run-it-from-ci).

## Keep the environment on the latest merged build

A build override applies to one run or review. Anything without an override uses the build stored on the environment: GitHub App auto-runs, scheduled runs, and chats. Unless you update that build, those runs test whatever build someone last picked in **Settings → Applications & Envs**.

Promote the build from CI instead. On every push to the default branch, build the app, upload it, then `PATCH` the environment with the new `applicationBuildShortId`:

```yaml theme={null}
name: Promote mobile build to QA.tech staging
on:
  push:
    branches: [main]

concurrency:
  group: qatech-promote-staging
  cancel-in-progress: true

jobs:
  promote:
    runs-on: ubuntu-latest
    env:
      QATECH_API_TOKEN: ${{ secrets.QATECH_API_TOKEN }}
      APP_ID: app_gXeBl2
      ENV_ID: env_staging_aB3xY9
      APK_PATH: app/build/outputs/apk/debug/app-debug.apk
    steps:
      - uses: actions/checkout@v4

      - name: Build APK
        run: ./gradlew assembleDebug

      - name: Upload build to QA.tech
        id: upload
        run: |
          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\", \"version\": \"${GITHUB_SHA::7}\"}")
          echo "build_short_id=$(echo "$BUILD_RESPONSE" | jq -r '.applicationBuildShortId')" >> "$GITHUB_OUTPUT"

      - name: Make it the staging environment's build
        run: |
          curl -sSf -X PATCH "https://api.qa.tech/v1/applications/$APP_ID/environments/$ENV_ID" \
            -H "Authorization: Bearer $QATECH_API_TOKEN" \
            -H "Content-Type: application/json" \
            -d "{\"applicationBuildShortId\": \"${{ steps.upload.outputs.build_short_id }}\"}"
```

Replace `app_gXeBl2`, `env_staging_aB3xY9`, and the APK path. Find the environment short ID with [List Application Environments](https://docs.qa.tech/api-reference/applications/list-application-environments.md) or the three-dot menu in **Settings → Applications & Envs**. The API key needs the `write` scope.

The request fails with `400` if the build belongs to another application or its platform differs from the environment's (an iOS build on an Android environment). Other apps on the environment stay as they are. To replace them, pass `otherApplicationBuildShortIds`, or `[]` to clear them. The response returns the environment in the same shape as the list endpoint, including the new `applicationBuildShortId`. See [Update Environment](https://docs.qa.tech/api-reference/applications/update-environment.md).

AI agents can do the same with the `update_environment` [MCP tool](https://docs.qa.tech/integrations/mcp.md).

## 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](https://app.qa.tech/current-project/settings/network) (**Mobile Testing IP Whitelist**). See [Network Access](https://docs.qa.tech/test-features/mobile-app-testing.md#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.

If auto-runs, scheduled runs, or chats test an old build, the environment still stores it. [Promote each merged build](#keep-the-environment-on-the-latest-merged-build) to that environment from CI.

**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](https://docs.qa.tech/test-features/mobile-app-testing.md#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](https://docs.qa.tech/pr-testing/github#change-review-action).

**Login or API calls fail in the emulator**

The backend is blocking mobile testing IPs. Update the [Mobile Testing IP Whitelist](https://docs.qa.tech/test-features/mobile-app-testing.md#network-access).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.