> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/mobile/llms.txt.
> For full documentation content, see https://docs.tester.army/mobile/llms-full.txt.

# 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](https://github.com/tester-army/mobile-github-action) and the [mobile example app](https://github.com/tester-army/mobile-example).

## What you need

Add these GitHub secrets to your repository:

| Secret                   | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `TESTERARMY_API_KEY`     | API key from **Team Settings → API Keys**              |
| `TESTERARMY_PROJECT_ID`  | Your TesterArmy project ID from **Project Settings**   |
| `TESTERARMY_WEBHOOK_URL` | Group webhook URL for the mobile tests you want to run |

You can find webhook details in [Group Webhooks](/run/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.

```yaml
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
        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

      - 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 }}"
```

> **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.

## Important options

| Input                   | Required | Description                                                       |
| ----------------------- | -------- | ----------------------------------------------------------------- |
| `app_path`              | Yes      | Path to the `.app`, `.app.zip`, or `.app.tar.gz` you want to test |
| `api_key`               | Yes      | TesterArmy API key                                                |
| `project_id`            | Yes      | TesterArmy project ID                                             |
| `webhook_url`           | Yes      | Group webhook URL                                                 |
| `delete_app_after_run`  | No       | Delete the uploaded app when the run finishes                     |
| `remove_after`          | No       | Auto-delete the upload after a number of seconds                  |
| `timeout_seconds`       | No       | Maximum time to wait for all runs to finish                       |
| `poll_interval_seconds` | No       | How 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:

```bash
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/app-uploads)
* API Reference tab
* [Group Webhooks](/run/group-webhooks)