Run your Flows on Maestro Cloud.

Add the following to your workflow. Note that you can use the v1 tag if you want to keep using the latest version of the action, which will automatically resolve to all v1.minor.patch versions as they get published.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' # replace this with your actual project id app-file: <path_to_your_app_file>

Trigger this action on (1) pushes to your main branch and (2) pull requests opened against your main branch:

on: push: branches: [master] pull_request: branches: [master]

If you need to use the pull_request_target trigger to support repo forks, check out the HEAD of the pull request to ensure that you're running the analysis against the changed code:

on: push: branches: [master] pull_request_target: branches: [master] jobs: upload-to-mobile-dev: name: Run Flows on Maestro Cloud steps: - uses: actions/checkout@v3 with: ref: ${{ github.event.pull_request.head.sha }} # Checkout PR HEAD

For more information on triggering workflows, check out GitHub's documentation.

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

app-file should point to an x86 compatible APK file, either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used.

Include the ProGuard mapping file to deobfuscate Android performance traces:

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

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: <app_name>.app mapping-file: <app_name>.app.dSYM

app-file should point to an .app build (x86 or ARM), either directly to the file or a glob pattern matching the file name. When using a pattern, the first matched file will be used.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: <app_name>.app mapping-file: <app_name>.app.dSYM

mapping-file should point to generated .dSYM file (unique per build). more info here.

By default, the action is looking for a .maestro folder with Maestro flows in the root directory of the project. If you would like to customize this behaviour, you can override it with a workspace argument:

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip workspace: myFlows/

A name will automatically be provided according to the following order:

1. If it is a Pull Request, use Pull Request title as name
2. If it is a normal push, use commit message as name
3. If for some reason the commit message is not available, use the commit SHA as name

If you want to override this behaviour and specify your own name, you can do so by setting the name argument:

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip name: My Upload

The action automatically detects the branch name from the GitHub context. However, in certain workflow triggers like issue_comment, repository_dispatch, or workflow_dispatch, the automatic detection may not work correctly because these events typically run on the default branch (main) regardless of which branch you actually want to test.

The branch input allows you to explicitly specify the branch name for these scenarios. This is particularly useful when:

• Running tests on a PR branch via issue_comment events (e.g., comment-triggered workflows)
• Triggering workflows via API with repository_dispatch
• Using workflow_dispatch to manually test a specific branch
• Any scenario where the GitHub context doesn't accurately reflect the branch you want to test
• You're making use of Maestro Cloud's 'Stop Previous Flows' feature, and want to be sure that the correct branch's flows are stopped.

Example usage with issue_comment trigger:

on: issue_comment: types: [created] jobs: test: if: contains(github.event.comment.body, '/test') runs-on: ubuntu-latest steps: - name: Get PR branch id: pr env: PR_NUMBER: ${{ github.event.issue.number }} GH_TOKEN: ${{ github.token }} run: |  HEAD_REF=$(gh pr view "$PR_NUMBER" --json headRefName --jq '.headRefName')  echo "branch=$HEAD_REF" >> $GITHUB_OUTPUT   - uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip branch: ${{ steps.pr.outputs.branch }} # Explicitly specify PR branch

If you don't want the action to wait until the Upload has been completed as is the default behaviour, set the async argument to true:

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip async: true

Alternatively, you might want to still wait for the action but would like to configure the timeout period, set timeout argument to a number of minutes:

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip timeout: 90 # Wait for 90 minutes

If you want to pass environment variables along with your upload, add a multiline env argument:

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip env: |  USERNAME=<username>  PASSWORD=<password>

You can use Maestro Tags to filter which Flows to send:

You can either pass a single value, or comma-separated (,) values.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip include-tags: dev, pull-request exclude-tags: excludeTag

You can specify which Android API level to use when running using the android-api-level parameter.

On Maestro Cloud, the default API level is 33 (Android 13). Refer to Maestro Cloud docs for available Android emulator API levels.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.apk android-api-level: 29

You can specify which iOS Version to use when running in Maestro Cloud using the device-os parameter.

On Maestro Cloud, the default iOS version is 16. Refer to Maestro Cloud docs for available iOS simulator versions. On Maestro Cloud, the default iOS version is 16.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip device-model: iPhone-16 device-os: iOS-18-2

If your workspace contains Web tests that are supposed to run on a real browser, specify device-os as web. You don't have to specify app-file.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' device-os: web

You can use an already uploaded binary in Maestro Cloud using the app-binary-id parameter.

- id: upload uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip - uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-binary-id: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }}

To switch the device locale on a remote device from a default one (en_US) device-locale parameter should be used. The value is a combination of lowercase ISO-639-1 code and uppercase ISO-3166-1 code, i.e. "de_DE" for Germany.

- uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: app.zip device-locale: de_DE

The following output variables are set by the action:

• MAESTRO_CLOUD_CONSOLE_URL - link to the Maestro Cloud console (if using Maestro Cloud)
• MAESTRO_CLOUD_UPLOAD_STATUS - status of the Upload (not available in async mode)
• MAESTRO_CLOUD_FLOW_RESULTS - list of Flows and their results (not available in async mode)
• MAESTRO_CLOUD_APP_BINARY_ID - id of the binary uploaded (if using Maestro Cloud)

In order to access these variables you can use the following approach:

- id: upload uses: mobile-dev-inc/action-maestro-cloud@v2.0.1 with: api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }} project-id: 'proj_01example0example1example2' app-file: <your_app_file> # ... any other parameters - name: Access Outputs if: always() run: |  echo "Console URL: ${{ steps.upload.outputs.MAESTRO_CLOUD_CONSOLE_URL }}"  echo "Flow Results: ${{ steps.upload.outputs.MAESTRO_CLOUD_FLOW_RESULTS }}"  echo "Upload Status: ${{ steps.upload.outputs.MAESTRO_CLOUD_UPLOAD_STATUS }}"  echo "App Binary ID: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }}"

• MAESTRO_CLOUD_UPLOAD_STATUS

  Any of the following values:

  PENDING PREPARING INSTALLING RUNNING SUCCESS ERROR CANCELED WARNING STOPPED 

• MAESTRO_CLOUD_FLOW_RESULTS

  An array of objects with at least name, status, and errors fields.

  [ { "name": "my-first-flow", "status": "SUCCESS", "errors": [] }, { "name": "my-second-flow", "status": "SUCCESS", "errors": [] }, { "name": "my-cancelled-flow", "status": "CANCELED", "errors": [], "cancellationReason": "INFRA_ERROR" } ]