{"id":18346160,"url":"https://github.com/mobile-dev-inc/action-maestro-cloud","last_synced_at":"2026-02-23T13:21:03.452Z","repository":{"id":78996462,"uuid":"560843174","full_name":"mobile-dev-inc/action-maestro-cloud","owner":"mobile-dev-inc","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-24T08:44:29.000Z","size":1023,"stargazers_count":26,"open_issues_count":5,"forks_count":17,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-29T07:54:34.072Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mobile-dev-inc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-02T11:50:16.000Z","updated_at":"2025-06-24T08:44:30.000Z","dependencies_parsed_at":"2023-11-15T12:30:16.088Z","dependency_job_id":"6d0bc40f-121b-46bc-a452-a46ca5b5dfa8","html_url":"https://github.com/mobile-dev-inc/action-maestro-cloud","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/mobile-dev-inc/action-maestro-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobile-dev-inc%2Faction-maestro-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobile-dev-inc%2Faction-maestro-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobile-dev-inc%2Faction-maestro-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobile-dev-inc%2Faction-maestro-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mobile-dev-inc","download_url":"https://codeload.github.com/mobile-dev-inc/action-maestro-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobile-dev-inc%2Faction-maestro-cloud/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264000628,"owners_count":23542112,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T21:10:41.852Z","updated_at":"2025-10-16T09:18:15.726Z","avatar_url":"https://github.com/mobile-dev-inc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Maestro Cloud Action\n\nRun your Flows on [Maestro Cloud](https://app.maestro.dev).\n\n## Using the action\n\nAdd 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.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2' # replace this with your actual project id\n    app-file: \u003cpath_to_your_app_file\u003e\n```\n\n## Inputs\n\n| Key                 | Required                 | Description                                                                                                                                                                                |\n| ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `api-key`           | Yes                      | Your Maestro Cloud API key                                                                                                                                                                 |\n| `android-api-level` | No                       | The Android API level to use when running the Flows                                                                                                                                        |\n| `app-file`          | Yes (or `app-binary-id`) | Path to the app file to upload.                                                                                                                                                            |\n| `app-binary-id`     | Yes (or `app-file`)      | The ID of a previously uploaded app-file.                                                                                                                                                  |\n| `async`             | No                       | Whether to start the flow and exit the action (defaults to `false`)                                                                                                                        |\n| `env`               | No                       | Environment variables to pass to the run                                                                                                                                                   |\n| `exclude-tags`      | No                       | Comma-separated list of tags to exclude from the run                                                                                                                                       |\n| `include-tags`      | No                       | Comma-separated list of tags to include in the run                                                                                                                                         |\n| `mapping-file`      | No                       | Path to the ProGuard map (Android) or dSYM (iOS)                                                                                                                                           |\n| `project-id`        | Yes                      | Which project to run the tests against                                                                                                                                                     |\n| `name`              | No                       | Friendly name of the run                                                                                                                                                                   |\n| `timeout`           | No                       | How long to wait for the run to complete when not async (defaults to 30 minutes)                                                                                                           |\n| `workspace`         | No                       | Path to the workspace directory containing the Flows (defaults to `.maestro`)                                                                                                              |\n| `device-model`      | No                       | The [device model](https://docs.maestro.dev/cloud/reference/configuring-os-version#using-a-specific-ios-minor-version-and-device-recommended) to use when running the Flows (eg iPhone-11) |\n| `device-os`         | No                       | The [device OS](https://docs.maestro.dev/cloud/reference/configuring-os-version) to use when running the Flows (eg iOS-16-2)                                                               |\n| `device-locale`     | No                       | The [device locale](https://docs.maestro.dev/cloud/reference/configuring-device-locale) to use when running the Flows (eg en_US)                                                           |\n\n## Triggers\n\nTrigger this action on (1) pushes to your main branch and (2) pull requests opened against your main branch:\n\n```yaml\non:\n  push:\n    branches: [master]\n  pull_request:\n    branches: [master]\n```\n\nIf 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:\n\n```yaml\non:\n  push:\n    branches: [master]\n  pull_request_target:\n    branches: [master]\njobs:\n  upload-to-mobile-dev:\n    name: Run Flows on Maestro Cloud\n    steps:\n      - uses: actions/checkout@v3\n        with:\n          ref: ${{ github.event.pull_request.head.sha }} # Checkout PR HEAD\n```\n\nFor more information on triggering workflows, check out [GitHub's documentation](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows).\n\n## Android\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app/build/outputs/apk/debug/app-debug.apk\n```\n\n`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.\n\n### ProGuard Deobfuscation\n\nInclude the ProGuard mapping file to deobfuscate Android performance traces:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app/build/outputs/apk/release/app-release.apk\n    mapping-file: app/build/outputs/mapping/release/mapping.txt\n```\n\n## iOS\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: \u003capp_name\u003e.app\n    mapping-file: \u003capp_name\u003e.app.dSYM\n```\n\n`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.\n\n### .dSYM file\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: \u003capp_name\u003e.app\n    mapping-file: \u003capp_name\u003e.app.dSYM\n```\n\n`mapping-file` should point to generated .dSYM file (unique per build). more info [here](https://developer.apple.com/documentation/xcode/building-your-app-to-include-debugging-information).\n\n## Custom workspace location\n\nBy 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:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    workspace: myFlows/\n```\n\n## Custom name\n\nA name will automatically be provided according to the following order:\n\n1. If it is a Pull Request, use Pull Request title as name\n2. If it is a normal push, use commit message as name\n3. If for some reason the commit message is not available, use the commit SHA as name\n\nIf you want to override this behaviour and specify your own name, you can do so by setting the `name` argument:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    name: My Upload\n```\n\n## Run in async mode\n\nIf 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`:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    async: true\n```\n\nAlternatively, 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:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    timeout: 90 # Wait for 90 minutes\n```\n\n## Adding environment variables\n\nIf you want to pass environment variables along with your upload, add a multiline `env` argument:\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    env: |\n      USERNAME=\u003cusername\u003e\n      PASSWORD=\u003cpassword\u003e\n```\n\n## Using tags\n\nYou can use Maestro [Tags](https://maestro.mobile.dev/cli/tags) to filter which Flows to send:\n\nYou can either pass a single value, or comma-separated (`,`) values.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    include-tags: dev, pull-request\n    exclude-tags: excludeTag\n```\n\n## Specifying Android API Level\n\nYou can specify which Android API level to use when running using the `android-api-level` parameter.\n\nOn Maestro Cloud, the default API level is 33 (Android 13). [Refer to Maestro Cloud docs](https://docs.maestro.dev/cloud/reference/configuring-os-version) for available Android emulator API levels.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.apk\n    android-api-level: 29\n```\n\n## Specifying iOS version and device\n\nYou can specify which iOS Version to use when running in Maestro Cloud using the `device-os` parameter.\n\nOn Maestro Cloud, the default iOS version is 16. [Refer to Maestro Cloud docs](https://docs.maestro.dev/cloud/reference/configuring-os-version) for available iOS simulator versions. On Maestro Cloud, the default iOS version is 16.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    device-model: iPhone-16\n    device-os: iOS-18-2\n```\n\n## Running Web tests\n\nIf your workspace contains Web tests that are supposed to run on a real browser, specify `device-os` as `web`.\nYou don't have to specify `app-file`.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    device-os: web\n```\n\n## Using an already uploaded App\n\nYou can use an already uploaded binary in Maestro Cloud using the `app-binary-id` parameter.\n\n```yaml\n- id: upload\n  uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-binary-id: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }}\n```\n\n## Configuring the locale for the device where the flows will be executed\n\nTo 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.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: app.zip\n    device-locale: de_DE\n```\n\n## Outputs\n\nThe following output variables are set by the action:\n\n- `MAESTRO_CLOUD_CONSOLE_URL` - link to the Maestro Cloud console (if using Maestro Cloud)\n- `MAESTRO_CLOUD_UPLOAD_STATUS` - status of the Upload (not available in `async` mode)\n- `MAESTRO_CLOUD_FLOW_RESULTS` - list of Flows and their results (not available in `async` mode)\n- `MAESTRO_CLOUD_APP_BINARY_ID` - id of the binary uploaded (if using Maestro Cloud)\n\nIn order to access these variables you can use the following approach:\n\n```yaml\n- id: upload\n  uses: mobile-dev-inc/action-maestro-cloud@v1.9.8\n  with:\n    api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}\n    project-id: 'proj_01example0example1example2'\n    app-file: \u003cyour_app_file\u003e\n    # ... any other parameters\n\n- name: Access Outputs\n  if: always()\n  run: |\n    echo \"Console URL: ${{ steps.upload.outputs.MAESTRO_CLOUD_CONSOLE_URL }}\"\n    echo \"Flow Results: ${{ steps.upload.outputs.MAESTRO_CLOUD_FLOW_RESULTS }}\"\n    echo \"Upload Status: ${{ steps.upload.outputs.MAESTRO_CLOUD_UPLOAD_STATUS }}\"\n    echo \"App Binary ID: ${{ steps.upload.outputs.MAESTRO_CLOUD_APP_BINARY_ID }}\"\n```\n\n### Output types\n\n- `MAESTRO_CLOUD_UPLOAD_STATUS`\n\n  Any of the following values:\n\n  ```plaintext\n  PENDING\n  PREPARING\n  INSTALLING\n  RUNNING\n  SUCCESS\n  ERROR\n  CANCELED\n  WARNING\n  STOPPED\n  ```\n\n- `MAESTRO_CLOUD_FLOW_RESULTS`\n\n  An array of objects with at least `name`, `status`, and `errors` fields.\n\n  ```json\n  [\n    { \"name\": \"my-first-flow\", \"status\": \"SUCCESS\", \"errors\": [] },\n    { \"name\": \"my-second-flow\", \"status\": \"SUCCESS\", \"errors\": [] },\n    {\n      \"name\": \"my-cancelled-flow\",\n      \"status\": \"CANCELED\",\n      \"errors\": [],\n      \"cancellationReason\": \"INFRA_ERROR\"\n    }\n  ]\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobile-dev-inc%2Faction-maestro-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmobile-dev-inc%2Faction-maestro-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobile-dev-inc%2Faction-maestro-cloud/lists"}