TesterArmyTesterArmy
TesterArmyTesterArmy
WelcomeIntroductionQuick Start
Run ModePull Request TestingProduction MonitoringGroup Webhooks
Test CredentialsAgent Mail InboxesHTTP Basic Auth
OverviewApp UploadsGitHub Actions
VercelCoolifyCoolifySlack
Testing Staging EnvironmentTesting PRs
Getting StartedLocal Development
Mobile

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.

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:

SecretDescription
TESTERARMY_API_KEYAPI key from Team Settings → API Keys

App Uploads

Previous Page

Vercel

Next Page

On this page

What you needRecommended workflowWhat the action doesImportant optionsOutputsTroubleshootingThe app upload fails immediatelyThe action cannot find your buildThe workflow starts but no tests runThe workflow times outRelated docs
TESTERARMY_PROJECT_IDYour TesterArmy project ID from Project Settings
TESTERARMY_WEBHOOK_URLGroup webhook URL for the mobile tests you want to run

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.
name: Mobile Tests

on:
  push:
    branches:
      - main
  pull_request:
  workflow_dispatch:

jobs:
  build:
    name: Build iOS Simulator app
    runs-on: macos-latest

    steps:
      - name: Check out repository

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.

Important options

InputRequiredDescription
app_pathYesPath to the .app, .app.zip, or .app.tar.gz you want to test
api_keyYesTesterArmy API key
project_idYesTesterArmy project ID
webhook_urlYesGroup webhook URL
delete_app_after_runNoDelete the uploaded app when the run finishes
remove_afterNoAuto-delete the upload after a number of seconds
timeout_secondsNoMaximum time to wait for all runs to finish
poll_interval_secondsNoHow often the action checks for run completion

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
  • Mobile Apps API
  • Group Webhooks
uses: actions/checkout@v5
- name: Build iOS Simulator app
shell: bash
run: |
set -euo pipefail
xcodebuild \
-workspace ios/MyApp.xcworkspace \
-scheme MyApp \
-configuration Release \
-sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
-derivedDataPath ios/build \
build \
CODE_SIGNING_ALLOWED=NO \
CODE_SIGNING_REQUIRED=NO
- name: Copy .app to artifact directory
shell: bash
run: |
set -euo pipefail
mkdir -p .build
cp -R ios/build/Build/Products/Release-iphonesimulator/MyApp.app .build/MyApp.app
- name: Upload .app artifact
uses: actions/upload-artifact@v5
with:
name: ios-simulator-app
path: .build/MyApp.app
retention-days: 1
test:
name: Run TesterArmy tests
needs: build
runs-on: ubuntu-latest
steps:
- name: Download .app artifact
uses: actions/download-artifact@v5
with:
name: ios-simulator-app
path: .build/MyApp.app
- name: Upload app and run TesterArmy tests
id: mobile
uses: tester-army/mobile-github-action@v1
with:
app_path: .build/MyApp.app
api_key: ${{ secrets.TESTERARMY_API_KEY }}
project_id: ${{ secrets.TESTERARMY_PROJECT_ID }}
webhook_url: ${{ secrets.TESTERARMY_WEBHOOK_URL }}
delete_app_after_run: "true"
remove_after: "3600"
timeout_seconds: "1800"
- name: Print overall status
run: echo "Overall status: ${{ steps.mobile.outputs.overall_status }}"