Generic CI platform

Integrate Maestro Cloud with any CI/CD provider using the CLI. Works with Jenkins, GitLab CI, Azure DevOps, and more.

You can run Maestro Flows in the cloud from any CI platform by using the Maestro CLI. This flexible approach works with Jenkins, GitLab CI, Azure DevOps, and more.

Maestro Cloud Plan required.

Cloud execution is available on the Maestro Cloud Plan.

Refer to the appropriate guide if you are using one of the following CI/CD integration options:

• GitHub Actions

• Bitrise

• Bitbucket Pipelines

• CircleCI

Prerequisites

• API Key: Get your API Key in the Maestro Dashboard.

• Project ID: Obtain your Project ID from your project settings in the dashboard.

• Build Compatibility:

  • Android: APKs must be ARMv8 compatible.

  • iOS: Simulator builds must be provided as a *.app directory or a zipped *.app.

Integration steps

1

Organize your Flows

Add your Flow files to a single directory in your repository.

<root>
├── e2e/
│   ├── subflows/
│   │   └── LoginSubflow.yaml
│   ├── Login.yaml
│   └── Search.yaml

In this configuration, files in the root of e2e run as top-level Flows. Files in subdirectories can be used as subflows that are not executed, but can be used by other flows at the top level.

2

Install the Maestro CLI

Ensure the Maestro CLI is installed on your CI runner:

curl -Ls "https://get.maestro.mobile.dev" | bash

3

Run the cloud command

Execute the maestro cloud command as part of your pipeline.

maestro cloud \
  --api-key "<YOUR_API_KEY>" \
  --project-id "<YOUR_PROJECT_ID>" \
  --name "<uploadName>" \
  --app-file "<APP_FILE>" \
  --flows "./e2e"

The following table describes all the parameter you must pass:

Parameter	Description
--api-key	Your Maestro Cloud API Key.
--project-id	Your Maestro Project ID.
--name	(Optional) A custom name for this specific upload.
--app-file	Path to your .apk or .app binary. Check the Build your app for the cloud guide for more information on how to build the app.
--flows	The directory containing your Flows.

For a complete list of advanced flags, refer to the Maestro CLI commands and options reference.

Troubleshooting: Connection timeouts

If your CI runner fails to start the Maestro driver within the default timeframe, you may see a timeout error.

The default timeout is 15 seconds (15000 ms) for Android and 120 seconds (120000 ms) for iOS.

You can extend this by setting a custom millisecond value in your pipeline environment. Here's an example to increase the timeout to 3 minutes (180000 ms):

export MAESTRO_DRIVER_STARTUP_TIMEOUT=180000

4

Handling results

Once your tests finish running, Maestro follows standard CI practices to let you know how they went:

• Exit Codes: The maestro cloud command returns 0 on success and 1 if any Flow fails. CI platforms typically use these exit codes to mark a build as failed.

• Reports: A link to the upload details in the Maestro Console is printed in the terminal logs for every run.

Next steps

Now that your CI pipeline is connected, consider optimizing your cloud runs:

• Set up notifications via Slack, email, or webhooks to stay informed about build and test results.

• Configure the operating system for your runs to match your application and dependency requirements.

• Define locales and time zones to ensure consistent behavior across environments and regions.

• Explore all the subcommand options for claud.