Platform guides

Set up Maestro Cloud GitHub Actions for Android, iOS, and Flutter.

This guide covers platform-specific configurations for setting up Maestro Cloud GitHub Actions.

To run tests on Android, you generally need to build an ARM compatible APK (typically a debug build) and upload it to Maestro Cloud.

Build command

Use Gradle to assemble your debug APK before the Maestro step.

- uses: actions/setup-java@v3
  with:
    java-version: 11
    distribution: 'temurin'

- run: ./gradlew assembleDebug

Action configuration

Point the app-file to your generated APK.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
  with:
    api-key: ${{ secrets.MAESTRO_API_KEY }}
    project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
    app-file: app/build/outputs/apk/debug/app-debug.apk

The app-file path supports glob patterns. If multiple files match, the first one is used.

ProGuard deobfuscation

If your app uses ProGuard/R8, you should upload the mapping file to deobfuscate performance traces and error logs.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
  with:
    api-key: ${{ secrets.MAESTRO_API_KEY }}
    project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
    app-file: app/build/outputs/apk/release/app-release.apk
    mapping-file: app/build/outputs/mapping/release/mapping.txt

Specifying the Android OS version and device

The default API level on Maestro Cloud is 33 (Android 13). You can override the OS version and the device model using device-os and device-model:

with:
  # ... other inputs
  device-model: pixel_6
  device-os: android-34

The android-api-level input is deprecated in favor of device-os. Run maestro list-cloud-devices to see all supported Android device models and OS versions.

Complete example for Android

The following code snippet shows a complete GitHub Action to build your Android app and test is using Maestro Cloud.

name: Build and run Maestro tests (Native Android)

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  maestro-cloud:
    runs-on: ubuntu-latest
    outputs:
      app: app/build/outputs/apk/debug
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: 11
          distribution: 'temurin'
      - run: ./gradlew assembleDebug
      - uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
        with:
          api-key: ${{ secrets.MAESTRO_API_KEY }}
          # note that you can supply the project id any way you like, it is not secret
          project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
          app-file: app/build/outputs/apk/debug/app-debug.apk

To run tests on iOS, you must build your app for the iOS Simulator. Real device builds (ARM64 only) are not supported on the Cloud emulators.

Build command

You must specify -destination 'generic/platform=iOS Simulator' to ensure the build is compatible with Maestro Cloud simulators.

- name: Build for Simulator
  run: |
    xcodebuild build \
      -scheme 'MyApp' \
      -configuration Debug \
      -project 'MyApp.xcodeproj' \
      -destination 'generic/platform=iOS Simulator' \
      CONFIGURATION_BUILD_DIR=$PWD/build

Action configuration

Point the app-file to the .app bundle generated in your build directory.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
  with:
    api-key: ${{ secrets.MAESTRO_API_KEY }}
    project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
    app-file: build/MyApp.app

Uploading symbol files (.dSYM)

To get symbolicated stack traces, include the generated .dSYM file.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
  with:
    api-key: ${{ secrets.MAESTRO_API_KEY }}
    project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
    app-file: build/MyApp.app
    mapping-file: build/MyApp.app.dSYM

Specify the iOS Version and device

The default iOS version is 16. You can specify a different OS version or device model if needed, using device-os and device-model respectively:

with:
  # ... other inputs
  device-model: iPhone-17-Pro
  device-os: iOS-26-2

The ios-version input is deprecated in favor of device-os. Run maestro list-cloud-devices to see all supported iOS device models and OS versions.

Complete example for iOS

The following code snippet shows a complete GitHub Action to build your iOS app and test is using Maestro Cloud.

name: Build and run Maestro tests (Native iOS)

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v2
      - run: xcodebuild build -scheme 'MyApp' -configuration Debug -project 'MyApp.xcodeproj' -destination 'generic/platform=iOS Simulator' CONFIGURATION_BUILD_DIR=$PWD/build
      - uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          # note that you can supply the project id any way you like, it is not secret
          project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
          app-file: build/MyApp.app

Flutter requires specific build flags to generate binaries compatible with Maestro Cloud.

Flutter Android

Build the APK in debug mode.

name: Build and run Maestro tests (Flutter Android)

on:
  workflow_dispatch:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          channel: "stable"
      - run: flutter build apk --debug
      - uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          # note that you can supply the project id any way you like, it is not secret
          project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
          app-file: build/app/outputs/flutter-apk/app-debug.apk

Flutter iOS

Build the iOS app for the simulator.

name: Build and run Maestro tests (Flutter iOS)

on:
  workflow_dispatch:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ios:
    runs-on: macos-13
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          channel: "stable"
      - run: flutter build ios --debug --simulator
      - uses: mobile-dev-inc/action-maestro-cloud@v2.0.2
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          # note that you can supply the project id any way you like, it is not secret
          project-id: ${{ secrets.MAESTRO_PROJECT_ID }}
          app-file: build/ios/iphonesimulator/Runner.app # replace `Runner` with your app name

Next Steps

Advanced configuration: Learn how to configure async mode, environment variables, and custom workspaces.
Outputs and triggers: Learn how to use action outputs and configure CI triggers.

PreviousGitHub Actions NextAdvanced configuration

Last updated 2 months ago