GitHub Action

The official BlueShork/maestro-action lets you run your Maestro flows on MaestroDeck Cloud straight from GitHub Actions. One step uploads your app and flows, runs them on a real simulator or emulator, waits for the result, and fails the build if the tests fail. No runner to provision, no simulator to boot in CI.

- uses: BlueShork/maestro-action@v5
  with:
    api_key: ${{ secrets.MAESTRO_API_KEY }}
    platform: android
    app: build/app-release.apk
    flow: .maestro/

How it works

The action uploads your build and flow files to MaestroDeck Cloud, runs them on the cloud device pool, polls for the result, and exits 0 (passed) or 1 (failed or error) so your pipeline goes green or red accordingly. Android jobs dispatch instantly; iOS jobs run on the macOS worker pool. It's the same pipeline as the web dashboard, triggered from CI.

Two things are worth their own page: web testing, where the target is a URL rather than a build, and visual regression, where the run compares its screenshots against a bank of references you keep in the repo.

Setup

Inputs

Outputs

Examples

Android

Build your APK in an earlier step, then hand its path to the action:

name: E2E
on: [push]
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # ... build your APK into build/app-release.apk ...
      - uses: BlueShork/maestro-action@v5
        with:
          api_key: ${{ secrets.MAESTRO_API_KEY }}
          platform: android
          app: build/app-release.apk
          flow: .maestro/

iOS

Point app at a zipped .app bundle and platform at ios:

- uses: BlueShork/maestro-action@v5
  with:
    api_key: ${{ secrets.MAESTRO_API_KEY }}
    platform: ios
    app: build/MyApp.app.zip
    flow: .maestro/login.yaml

Using the outputs

Read report_url, status or job_id in later steps. Use if: always() so the link is printed even when the run fails:

- uses: BlueShork/maestro-action@v5
  id: maestro
  with:
    api_key: ${{ secrets.MAESTRO_API_KEY }}
    platform: android
    app: build/app-release.apk
    flow: .maestro/
- if: always()
  run: echo "Report: ${{ steps.maestro.outputs.report_url }}"

Notes

• flow accepts a single file (.maestro/login.yaml), a glob (.maestro/*.yaml), or a directory (.maestro/, which picks up every .yaml / .yml inside).
• Each step invocation consumes one run from your MaestroDeck quota.
• The action needs curl and jq, both preinstalled on GitHub-hosted runners.
• Pin to a version tag (@v5) for stable behaviour, or pin a full SHA if you want byte-for-byte reproducibility. @v1 predates web and visual regression support.