GitHub Actions

GitHub Actions is the recommended way to run mobile tests automatically.

You only need to provide an iOS Simulator build or Android APK and your TesterArmy credentials. TesterArmy handles the cloud simulator/emulator setup, app installation, test execution, and run orchestration for you, so you do not need to manage devices in your CI pipeline.

For Expo EAS workflows, see Expo EAS.

Before you set it up, make sure you have already:

• built and uploaded a mobile app artifact,
• created at least one mobile test in TesterArmy,
• run that test manually once,
• added the test to a group.

If you want a working reference, see the mobile GitHub Action and the mobile example app.

What you need

Add these GitHub secrets to your repository:

You can copy the group ID from the test group menu in the dashboard.

Recommended workflow

The most reliable setup is:

1. Build the app artifact in a dedicated job.
2. Upload the .app bundle or .apk as a GitHub artifact.
3. Download that artifact on Linux.
4. Run tester-army/mobile-github-action with the matching platform to upload the app, run the group, wait for results, and clean up.

1
name: iOS Mobile Tests
2
3
on:
4
  push:
5
    branches:
6
      - main
7
  pull_request:
8
  workflow_dispatch:
9
10
permissions:
11
  contents: read
12
13
jobs:
14
  build_ios:
15
    name: Build iOS Simulator app
16
    runs-on: macos-latest
17
18
    steps:
19
      - name: Check out repository
20
        uses: actions/checkout@v5
21
22
      - name: Build iOS Simulator app
23
        shell: bash
24
        run: |
25
          set -euo pipefail
26
          xcodebuild \
27
            -workspace ios/MyApp.xcworkspace \
28
            -scheme MyApp \
29
            -configuration Release \
30
            -sdk iphonesimulator \
31
            -destination 'generic/platform=iOS Simulator' \
32
            -derivedDataPath ios/build \
33
            build
34
35
      - name: Copy .app to artifact directory
36
        shell: bash
37
        run: |
38
          set -euo pipefail
39
          mkdir -p .build
40
          cp -R ios/build/Build/Products/Release-iphonesimulator/MyApp.app .build/MyApp.app
41
42
      - name: Upload .app artifact
43
        uses: actions/upload-artifact@v5
44
        with:
45
          name: ios-simulator-app
46
          path: .build/MyApp.app
47
          retention-days: 1
48
49
  test_ios:
50
    name: Run iOS TesterArmy tests
51
    needs: build_ios
52
    runs-on: ubuntu-latest
53
54
    steps:
55
      - name: Download .app artifact
56
        uses: actions/download-artifact@v5
57
        with:
58
          name: ios-simulator-app
59
          path: .build/MyApp.app
60
61
      - name: Upload app and run TesterArmy tests
62
        id: mobile
63
        uses: tester-army/mobile-github-action@v1
64
        with:
65
          app_path: .build/MyApp.app
66
          platform: ios
67
          api_key: ${{ secrets.TESTERARMY_API_KEY }}
68
          project_id: ${{ secrets.TESTERARMY_PROJECT_ID }}
69
          group_id: ${{ secrets.TESTERARMY_GROUP_ID }}
70
          delete_app_after_run: "true"
71
          remove_after: "3600"
72
          timeout_seconds: "1800"
73
74
      - name: Print overall status
75
        run: echo "Overall status: ${{ steps.mobile.outputs.overall_status }}"

What the action does

tester-army/mobile-github-action handles the full CI flow for you:

1. Uploads the app to TesterArmy.
2. Provisions the cloud simulator or emulator environment and installs the app for the run.
3. Starts your mobile test group and orchestrates the run lifecycle.
4. Polls until the runs finish or the timeout is reached.
5. Deletes the uploaded app after the run if cleanup is enabled.

Results are written to the GitHub step summary so you can quickly see pass/fail status, duration, issues, and screenshots.

Direct CLI usage

For CI providers such as Expo EAS, Fastlane, Buildkite, or GitLab CI, upload the app with testerarmy upload-app, then use the returned app ID in the provider-agnostic CLI flow:

$
testerarmy ci \
>
  --group "$GROUP_ID" \
>
  --project "$PROJECT_ID" \
>
  --platform ios \
>
  --app-id "$APP_ID" \
>
  --commit-sha "$COMMIT_SHA" \
>
  --pr-number "$PR_NUMBER"

Use --platform android for Android app runs. ci calls POST /api/v1/groups/{groupId}/runs, waits for every returned run to finish, and deletes only the explicit --app-id when cleanup is enabled and the run did not time out.

Dynamic PR exploration

To run the dynamic PR agent against a mobile build instead of a predefined test group, call the pull request run API with platform: "ios" or "android" and a mobile app selector:

$
curl -X POST "https://tester.army/api/v1/projects/$PROJECT_ID/pull-request-runs" \
>
  -H "Authorization: Bearer $TESTERARMY_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "platform": "android",
>
    "pullRequest": {
>
      "number": 123,
>
      "title": "Improve onboarding",
>
      "description": "PR body or CI summary",
>
      "commitSha": "'$GITHUB_SHA'"
>
    },
>
    "mobile": {
>
      "appId": "'$TESTERARMY_APP_ID'"
>
    }
>
  }'

Use platform: "ios" with an iOS Simulator .app build or platform: "android" with an Android .apk. You can use mobile.appId, mobile.bundleId, or mobile.artifactUrl with mobile.artifactFilename. The endpoint does not require changed files; if a supported GitHub connection exists, TesterArmy enriches the plan server-side.

Important options

Outputs

The action exposes these outputs:

• app_id — the uploaded TesterArmy app ID
• run_ids — a JSON array of created run IDs
• overall_status — passed, failed, or timed_out

You can use overall_status in later workflow steps if you want custom reporting or notifications.

Troubleshooting

The app upload fails immediately

Make sure you are passing an iOS Simulator .app / .app.zip or an Android .apk. An .ipa, .aab, or .xapk will not work.

The action cannot find your build

Double-check the app path inside the build job. The most common iOS output path is:

$
ios/build/Build/Products/Release-iphonesimulator/MyApp.app

For Android release .apk files, the output is usually under:

$
android/app/build/outputs/apk/release/

The workflow starts but no tests run

Make sure your TESTERARMY_GROUP_ID points to a group that already contains mobile tests.

Related docs

• App Uploads
• Expo EAS
• API reference