Maestro in CI with GitHub Actions
Add a Maestro test job to a GitHub Actions workflow, start an Android emulator in CI, run the Maestro suite, and upload the result artifacts on failure.
Maestro in CI with GitHub Actions is a free React Native Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the React Native Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why Run Maestro in CI?
Running Maestro tests locally on your machine catches bugs before you push. Running them in CI (Continuous Integration) catches bugs before they reach main and are seen by other team members. Every pull request can automatically trigger the E2E suite and block merging if any test fails.
GitHub Actions is the most popular CI platform for open-source and small-team projects. It runs workflows defined in YAML files inside .github/workflows/. An Android emulator runs inside a GitHub-hosted Linux runner, while iOS requires a macOS runner.
GitHub Actions Workflow Basics
A GitHub Actions workflow file defines triggers (when to run), jobs (parallel or sequential work units), and steps (individual commands within a job). Each job runs on a fresh virtual machine specified by the runs-on key.
Maestro E2E tests require a running Android emulator or iOS Simulator. Android emulators run on ubuntu-latest runners. iOS Simulators require macos-latest runners, which are more expensive in GitHub Actions minutes.
# .github/workflows/e2e.yml
name: E2E Tests
on:
pull_request:
branches: [main, develop]
push:
branches: [main]
jobs:
e2e-android:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Maestro E2E Tests
run: echo 'Steps to follow...'Starting an Android Emulator in CI
The reactivecircus/android-emulator-runner GitHub Action starts an Android Virtual Device (AVD) inside the CI runner, runs your commands with the emulator available, and shuts it down after. It handles AVD creation, booting, and waiting for the device to be ready.
Choose a recent API level (api-level: 33 is Android 13) and set target: google_apis if your app uses Google Play Services or Google Maps. The emulator boot can take 2-5 minutes on GitHub's shared runners, so budget for this in your CI time estimates.
jobs:
e2e-android:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Java
uses: actions/setup-java@v4
with:
java-version: '17'
distribution: 'temurin'
- name: Enable KVM (hardware acceleration)
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: Run Android Emulator
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 33
arch: x86_64
script: echo 'Emulator is ready'Installing Maestro in CI
Install the Maestro CLI in the CI runner before running tests. Add the installation step to your workflow. Maestro's install script downloads the binary and adds it to the PATH.
After installation, verify the CLI is available with maestro --version. Add ~/.maestro/bin to the PATH environment variable for the rest of the workflow steps to find the binary.
- name: Install Maestro CLI
run: |
curl -Ls 'https://get.maestro.mobile.dev' | bash
echo '$HOME/.maestro/bin' >> $GITHUB_PATH
- name: Verify Maestro installation
run: maestro --versionBuilding and Installing the APK
Before Maestro can test the app, the APK (Android Package) must be built and installed on the emulator. Build the debug APK with Gradle and install it with adb install. For Expo apps, use EAS Build or npx expo run:android --variant release locally and commit the resulting APK as a build artifact.
To speed up CI, cache the Gradle build artifacts between runs using actions/cache. This reduces the build step from 5-10 minutes to 1-2 minutes on subsequent runs.
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Build Debug APK
run: cd android && ./gradlew assembleDebug
- name: Install APK on emulator
run: adb install android/app/build/outputs/apk/debug/app-debug.apkRunning the Maestro Test Suite
Run all Maestro flows with maestro test pointing to your flows directory. Use the --format flag to produce a JUnit XML report that GitHub Actions can display in the pull request UI as a test summary.
Pass environment variables from GitHub Secrets using -e KEY=${{ secrets.KEY }}. Store test account credentials in GitHub Secrets (Settings > Secrets) to keep them out of your repository code.
- name: Run Maestro E2E Tests
env:
TEST_EMAIL: ${{ secrets.E2E_TEST_EMAIL }}
TEST_PASSWORD: ${{ secrets.E2E_TEST_PASSWORD }}
run: |
maestro test \
-e TEST_EMAIL=$TEST_EMAIL \
-e TEST_PASSWORD=$TEST_PASSWORD \
--format junit \
--output test-results.xml \
maestro/flows/Uploading Test Results and Screenshots
Use actions/upload-artifact to save the JUnit XML report and Maestro's failure screenshots as CI artifacts. These are available for download from the GitHub Actions run page for 90 days. When a test fails, download the artifacts to see exactly which screen the test was on when it failed.
Run the upload step with if: always() so it executes even when the test job fails. Without this, a failing test would prevent the artifact upload and you would have no debugging information.
- name: Upload test results
if: always() # Upload even if tests fail
uses: actions/upload-artifact@v4
with:
name: e2e-test-results
path: |
test-results.xml
~/.maestro/tests/
retention-days: 30
- name: Publish Test Report
if: always()
uses: mikepenz/action-junit-report@v4
with:
report_paths: 'test-results.xml'
check_name: 'E2E Test Results'Caching Dependencies for Speed
The biggest time cost in a CI E2E job is usually installing Node modules, building the app, and booting the emulator. Cache node_modules between runs to skip npm install on every push. Cache the Android Gradle build to skip recompiling unchanged native code.
Use a cache key that includes a hash of your package-lock.json so the cache is invalidated when dependencies change. A well-cached job reduces from 20 minutes to under 10 minutes for most React Native projects.
- name: Cache Node modules
uses: actions/cache@v4
with:
path: node_modules
key: node-${{ hashFiles('package-lock.json') }}
restore-keys: node-
- name: Cache Gradle
uses: actions/cache@v4
with:
path: |
~/.gradle/caches
~/.gradle/wrapper
android/.gradle
key: gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
restore-keys: gradle-Running Maestro on iOS in CI
iOS E2E tests require a macOS runner because iOS Simulators only run on macOS. Use runs-on: macos-latest and select the simulator with xcrun simctl. Boot the simulator before installing the app and running Maestro.
iOS CI jobs are 10x more expensive in GitHub Actions minutes than Linux jobs. Run iOS E2E only on PRs to main or on a scheduled nightly build, not on every push to feature branches.
e2e-ios:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Start iOS Simulator
run: |
xcrun simctl boot 'iPhone 16'
open -a Simulator
- name: Install dependencies
run: npm ci
- name: Build iOS app
run: npx expo run:ios --configuration Release --no-bundler
- name: Install Maestro
run: curl -Ls 'https://get.maestro.mobile.dev' | bash && echo '$HOME/.maestro/bin' >> $GITHUB_PATH
- name: Run E2E Tests
run: maestro test maestro/flows/ --format junit --output ios-results.xmlHandling Flaky Tests in CI
Flaky tests — tests that sometimes pass and sometimes fail with no code changes — are a major CI reliability problem. Common causes in Maestro are: animations not finishing before assertions, slow emulator performance in CI, and network-dependent tests that fail on timeouts.
Strategies to reduce flakiness: use waitForAnimationToEnd generously, increase assertion timeouts on network-dependent steps, use clearState: true to ensure each test starts clean, and mock the backend API with a test server so responses are instant and deterministic.
# Add retry logic at the workflow level for flaky suites
- name: Run Maestro (with retry)
uses: nick-fields/retry@v3
with:
timeout_minutes: 15
max_attempts: 2
command: |
maestro test \
--format junit \
--output test-results.xml \
maestro/flows/Integrating with Maestro Cloud
Maestro Cloud (cloud.mobile.dev) is a hosted service by the Maestro team that runs your E2E tests on real devices without requiring you to manage emulators in CI. You push your app binary and flow files, and Maestro Cloud runs them on a fleet of real iOS and Android devices.
Integrate Maestro Cloud into GitHub Actions with the mobile-dev-inc/action-maestro-cloud action. It handles device provisioning, test execution, and result reporting. Real device testing catches device-specific bugs that emulators miss.
- name: Upload to Maestro Cloud
uses: mobile-dev-inc/action-maestro-cloud@v1
with:
api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
app-file: android/app/build/outputs/apk/debug/app-debug.apk
workspace: maestro/flows/
env: |
TEST_EMAIL=${{ secrets.E2E_TEST_EMAIL }}
TEST_PASSWORD=${{ secrets.E2E_TEST_PASSWORD }}Quick Check
Test your understanding of React Native Mobile Development concepts from this lesson.
Lesson Recap
In this lesson you learned: how to write a GitHub Actions workflow that starts an Android emulator, installs Maestro, and runs E2E flows automatically on pull requests, how to cache node_modules and Gradle artifacts to speed up CI runs, and how to upload test results and failure screenshots as artifacts for post-failure debugging. Congratulations on completing the E2E Testing with Maestro course — your app now has a complete testing pyramid from unit tests through end-to-end flows.
Frequently asked questions
Is the “Maestro in CI with GitHub Actions” lesson free?
Yes — the full text of “Maestro in CI with GitHub Actions” is free to read here on the web, and the React Native Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the React Native Academy course, upgrade to CoddyKit PRO.
What will I learn in “Maestro in CI with GitHub Actions”?
Add a Maestro test job to a GitHub Actions workflow, start an Android emulator in CI, run the Maestro suite, and upload the result artifacts on failure. You practise React Native Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start React Native Academy?
No prior experience is required. React Native Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Maestro in CI with GitHub Actions” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this React Native Academy lesson?
Yes. Every React Native Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Installing Maestro and Running Your First Flow
- Assertions and Waiting for Elements
- Testing Multi-Screen User Journeys
- Maestro in CI with GitHub Actions