GitHub Actions

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

You only need to provide a simulator build and your TesterArmy credentials. TesterArmy handles the cloud simulator setup, app installation, test execution, and run orchestration for you, so you do not need to manage simulators 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 simulator app,
• created at least one mobile test in TesterArmy,
• run that test manually once,
• added the test to a group with a webhook.

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 find webhook details in Group Webhooks.

Recommended workflow

The most reliable setup is:

1. Build the iOS Simulator app on a macOS runner.
2. Upload the .app bundle as a GitHub artifact.
3. Download that artifact on Linux.
4. Run tester-army/mobile-github-action to upload the app, trigger the webhook, wait for results, and clean up.

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

Info: No manual upload step in CI

The GitHub Action accepts either a .app directory or an archived app file. If you pass a .app directory, the action zips and uploads it for you.

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 environment and installs the app for the run.
3. Triggers your mobile test group webhook 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, use the provider-agnostic CLI flow:

$
testerarmy ci \
>
  --group "$GROUP_ID" \
>
  --project "$PROJECT_ID" \
>
  --commit-sha "$COMMIT_SHA" \
>
  --pr-number "$PR_NUMBER"

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.

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 building for iOS Simulator and passing a .app, .app.zip, or .app.tar.gz file. An .ipa will not work.

The action cannot find your build

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

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

The workflow starts but no tests run

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

The workflow times out

Increase timeout_seconds for slower builds or longer test suites. The default is 30 minutes.

Related docs

• App Uploads
• Expo EAS
• API reference
• Group Webhooks