CI integration

Integrating MobileBoost into your CI pipeline enables automated test execution against your latest app builds.

GitHub Action

The MobileBoost Test Action uploads your build and sends the PR body (which should contain test instructions) to MobileBoost in a single step.

name: MobileBoost tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Build project
        run: |
          # Build your project and generate the build file

      - name: Trigger MobileBoost tests
        uses: MobileBoostHQ/mobileboost-test-action@v1
        with:
          organisation-id: ${{ secrets.MOBILEBOOST_ORG_ID }}
          app-path: path/to/your/build.apk
          platform: android

The action automatically extracts test instructions from your PR body and sends them along with the build artifact. For guidance on formatting test instructions, see the format requirements section in the Natural language test definitions page.

If your app talks to a staging environment that is not reachable from the public internet, open a tunnel in the same job so the devices can reach it. See Local testing in CI.

Inputs

Input	Required	Description
`organisation-id`	Yes	Your MobileBoost organisation ID
`app-path`	Yes	Path to the `.apk` or `.ipa` build file
`platform`	Yes	App platform: `Android` or `iOS`

Required secrets

Add MOBILEBOOST_ORG_ID to your repository under Settings > Secrets and variables > Actions.

CI provider snippets

For other CI systems, use the upload API to send your build artifact and capture the returned buildId.

In all examples below, replace <ORG_KEY> with your MobileBoost organisation key, <platform> with ios or android, and the build file path with the actual path to your artifact.

Bitrise
GitLab CI
CircleCI
Jenkins

Add a Script step to your workflow after the build step. This uploads the build and makes the buildId available as an environment variable for subsequent steps.

call=$(curl -i -X POST \
        -H "Content-Type: multipart/form-data" \
        -F "build=@$BITRISE_BUILD_PATH" \
        -F "organisation_key=<ORG_KEY>" \
        -F "platform=<platform>" \
        -F "metadata={}" \
        https://api.mobileboost.io/uploadBuild/)

buildId=$(echo "$call" | awk '/^{/ {print}' | jq -r '.buildId')

envman add --key MOBILEBOOST_BUILD_ID --value $buildId

Link each build to its pull request (recommended). Pass a ci field so MobileBoost knows which pull request produced each build. Results then map back to the right PR, and MobileBoost can select the tests relevant to that PR’s changes. Every value comes from a built-in Bitrise variable, so there is nothing extra to create.

# Assemble the ci payload from Bitrise's built-in PR variables
CI_JSON=$(jq -n \
  --arg repo      "$BITRISEIO_GIT_REPOSITORY_OWNER/$BITRISEIO_GIT_REPOSITORY_SLUG" \
  --arg commitSha "$BITRISE_GIT_COMMIT" \
  --arg branch    "${BITRISEIO_GIT_BRANCH_DEST:-$BITRISE_GIT_BRANCH}" \
  --arg prNumber  "$BITRISE_PULL_REQUEST" \
  '{repo: $repo, commitSha: $commitSha, branch: $branch}
   + (if $prNumber != "" then {prNumber: ($prNumber | tonumber)} else {} end)')

call=$(curl -i -X POST \
        -H "Content-Type: multipart/form-data" \
        -F "build=@$BITRISE_BUILD_PATH" \
        -F "organisation_key=<ORG_KEY>" \
        -F "platform=<platform>" \
        -F "ci=$CI_JSON" \
        https://api.mobileboost.io/uploadBuild/)

buildId=$(echo "$call" | awk '/^{/ {print}' | jq -r '.buildId')

envman add --key MOBILEBOOST_BUILD_ID --value "$buildId"

Each ci field maps to a variable Bitrise sets automatically:

`ci` field	Bitrise variable	Availability
`repo`	`$BITRISEIO_GIT_REPOSITORY_OWNER` / `$BITRISEIO_GIT_REPOSITORY_SLUG`	Always
`commitSha`	`$BITRISE_GIT_COMMIT`	Always
`branch`	`$BITRISEIO_GIT_BRANCH_DEST`, falling back to `$BITRISE_GIT_BRANCH`	PR destination branch on PR builds; current branch otherwise
`prNumber`	`$BITRISE_PULL_REQUEST` (the PR number)	Pull-request-triggered builds only

$BITRISE_PULL_REQUEST and $BITRISEIO_GIT_BRANCH_DEST are only set on pull-request-triggered builds, so make sure your workflow runs on pull requests (App settings > Triggers). On non-PR builds the snippet omits prNumber and links the build by commit instead - no changes needed.

The only value you provide yourself is your organisation key - store it as a Secret (App settings > Secrets) and reference it (for example $MOBILEBOOST_ORG_KEY) instead of hardcoding <ORG_KEY>. The build path is whatever your build step produces ($BITRISE_APK_PATH for Android, $BITRISE_IPA_PATH for iOS).

Add an upload stage to your .gitlab-ci.yml pipeline:

stages:
  - build
  - upload

build_job:
  stage: build
  script:
    - echo "Building the project..."
    # Build your project and generate the build file
    - export BUILD_FILE_PATH=path/to/your/build_file.apk

upload_job:
  stage: upload
  script:
    - echo "Uploading the build..."
    - >
      call=$(curl -i -X POST
                   -H "Content-Type: multipart/form-data"
                   -F "build=@${BUILD_FILE_PATH}"
                   -F "organisation_key=<ORG_KEY>"
                   -F "platform=<platform>"
                   -F "metadata={}"
                   https://api.mobileboost.io/uploadBuild/);
      buildId=$(echo "$call" | awk '/^{/ {print}' | jq -r '.buildId')
      echo "MobileBoost buildId: ${buildId}"

Add an upload-build job to your .circleci/config.yml:

version: 2.1

jobs:
  upload-build:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout

      - run:
          name: Install dependencies
          command: |
            sudo apt-get update
            sudo apt-get install -y jq curl

      - run:
          name: Build project
          command: |
            echo "Building the project..."
            # Replace with your actual build commands

      - run:
          name: Upload build to MobileBoost
          command: |
            response=$(curl -i -X POST \
                        -H "Content-Type: multipart/form-data" \
                        -F "build=@<build_file_path>" \
                        -F "organisation_key=<ORG_KEY>" \
                        -F "platform=<platform>" \
                        -F "metadata={}" \
                        https://api.mobileboost.io/uploadBuild/)

            if [ $? -ne 0 ]; then
              echo "Error: Failed to execute the curl command."
              exit 1
            fi

            status_code=$(echo "$response" | awk '/HTTP\// {print $2}' | tail -n1)
            if [ "$status_code" != "200" ]; then
              echo "Error: Upload failed with HTTP status code $status_code."
              echo "Response: $response"
              exit 1
            fi

            json_response=$(echo "$response" | awk '/^{/ {print}')
            buildId=$(echo "$json_response" | jq -r '.buildId')
            if [ -z "$buildId" ] || [ "$buildId" == "null" ]; then
              echo "Error: buildId not found in response."
              exit 1
            fi

            echo "Build ID: $buildId"
            echo "export BUILD_ID=$buildId" >> $BASH_ENV

workflows:
  build_and_upload:
    jobs:
      - upload-build

Add an Upload Build stage to your Jenkinsfile:

pipeline {
    agent any

    environment {
        ORG_KEY = '<ORG_KEY>'
        PLATFORM = '<platform>'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                script {
                    // Replace with your actual build commands
                }
            }
        }

        stage('Upload Build to MobileBoost') {
            steps {
                script {
                    def buildFilePath = 'path/to/your/build/file'
                    def response = httpRequest httpMode: 'POST',
                                             url: 'https://api.mobileboost.io/uploadBuild/',
                                             contentType: 'MULTIPART_FORMDATA',
                                             multipartNameValue: [
                                                 [name: 'build', fileName: buildFilePath,
                                                  mimeType: 'application/octet-stream'],
                                                 [name: 'organisation_key', value: ORG_KEY],
                                                 [name: 'platform', value: PLATFORM],
                                                 [name: 'metadata', value: '{}']
                                             ]
                    def responseBody = response.content
                    def buildId = sh(
                        script: "echo '${responseBody}' | jq -r '.buildId'",
                        returnStdout: true
                    ).trim()
                    env.BUILD_ID = buildId
                    echo "Build ID: ${buildId}"
                }
            }
        }
    }

    post {
        always {
            echo "Build and upload completed"
        }
    }
}

API

For full control, use the API directly. The process has three steps: upload the build, start a run, then read its results. Send your API key as Authorization: Bearer mb_live_... on each call.

Step 1: Upload the build

Upload your build artifact using the upload endpoint. The response returns a buildId.

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "build=@path/to/your/build.apk" \
  -F "organisation_key=YOUR_ORG_KEY" \
  -F "platform=android" \
  -F "metadata={}" \
  https://api.mobileboost.io/uploadBuild/

Step 2: Start a run

Send the buildId from step 1 to POST /tests/execute. Run specific tests by ID:

{
  "organisationId": "org123",
  "buildId": "BUILD_ID_FROM_STEP_1",
  "testIds": ["test_abc", "test_def"]
}

Run tests by tags: tags runs every test that has at least one of the tags. Send testIds as well to add specific tests to the run.

{
  "organisationId": "org123",
  "buildId": "BUILD_ID_FROM_STEP_1",
  "tags": ["critical"]
}

Run the newest build with a name: If your pipeline doesn’t keep the buildId, name the build instead. The run uses the newest build uploaded under that name for platform:

{
  "organisationId": "org123",
  "build": { "meta": { "name": "my-app" } },
  "platform": "android",
  "tags": ["critical"],
  "trigger": "ci"
}

Field	Required	Description
`organisationId`	Yes	Your organisation ID. It must be the organisation of your API key.
`buildId`	One of `buildId`, `build` or `bundleId`	The `buildId` from step 1.
`build.meta.name`		The newest build uploaded under this name.
`bundleId`		An app already installed on your reserved device, instead of an uploaded build. Requires `platform`, and has to be enabled for your organisation.
`testIds`	`testIds`, `tags`, or both	IDs of the tests to run.
`tags`		Run every test with at least one of these tags.
`platform`	With `bundleId`	`ios` or `android`. Otherwise taken from the build.
`usePhysicalDevice`	No	`true` for a real handset, `false` for an emulator or simulator. See Device configuration.
`tunnelName`	No	A MobileBoost Local tunnel for apps that call internal hosts. See Test against internal environments.
`trigger`	No	A label stored on the run, such as `ci`. Defaults to `api`.

Every selected test must be runnable on the platform: its automation has been written and verified. GET /tests shows this as platforms.<platform>.runnable. The response carries the ID of the run in runId:

{
  "message": "Autotest run created",
  "runId": "b1111111df174791a93e560390ea7e65",
  "status": "running"
}

deviceConfigs, deviceProviderSettings, launchParams, testInputs, tagsQuery, iterations and metaData are not supported. A request that sends any of them is refused with 400, so a run never goes ahead on settings it ignored.

Step 3: Get the results

Pass runId to GET /runs/{runId}, and repeat the call until status is completed or cancelled:

curl https://api.mobileboost.io/runs/b1111111df174791a93e560390ea7e65 \
  -H "Authorization: Bearer mb_live_..."

{
  "runId": "b1111111df174791a93e560390ea7e65",
  "status": "completed",
  "totalTests": 2,
  "runtimeSeconds": 212,
  "succeededTests": [
    {
      "id": "e4a1c7f09b2d4e56a8f3c1d2b7e90a11",
      "title": "test_login_flow.py",
      "status": "succeeded",
      "runtimeSeconds": 94,
      "recording": "https://platform.mobileboost.io/reports/b1111111df174791a93e560390ea7e65/e4a1c7f09b2d4e56a8f3c1d2b7e90a11"
    }
  ],
  "failedTests": [
    {
      "id": "7c2e9d10a4b84f3e9e5d6a7b8c9d0e12",
      "title": "test_checkout_flow.py",
      "status": "failed",
      "runtimeSeconds": 118,
      "recording": "https://platform.mobileboost.io/reports/b1111111df174791a93e560390ea7e65/7c2e9d10a4b84f3e9e5d6a7b8c9d0e12"
    }
  ],
  "blockedTests": [],
  "runningTests": [],
  "queuedTests": []
}

completed means every test has finished, not that every test passed. Fail your pipeline when failedTests is not empty.
While the run is in progress, runningTests and queuedTests show which tests are on a device and which are waiting for one.
Step 2 returns just before the run is saved, which usually takes under half a second. Wait 2 seconds before your first call. If it answers 404, retry every 2 seconds. A 404 that lasts longer than 30 seconds means the run was not created: check the runId, then start the run again.
While status is initial, tests are still being added to the run, so totalTests can still grow. This takes up to about 10 seconds for a run of 100 tests.

A minimal polling loop:

RUN_ID=$(curl -s -X POST https://api.mobileboost.io/tests/execute \
  -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organisationId": "org123", "buildId": "'"$BUILD_ID"'", "tags": ["critical"]}' \
  | jq -r '.runId')

# The run is saved just after the call returns: allow it up to 30 seconds.
for attempt in $(seq 1 15); do
  sleep 2
  CODE=$(curl -s -o /dev/null -w '%{http_code}' https://api.mobileboost.io/runs/$RUN_ID \
    -H "Authorization: Bearer $MOBILEBOOST_API_KEY")
  [ "$CODE" != "404" ] && break
done
if [ "$CODE" = "404" ]; then echo "Run $RUN_ID was not created"; exit 1; fi

while true; do
  RESULT=$(curl -s https://api.mobileboost.io/runs/$RUN_ID \
    -H "Authorization: Bearer $MOBILEBOOST_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "Run $RUN_ID: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "cancelled" ]; then break; fi
  sleep 30
done

[ "$(echo "$RESULT" | jq '.failedTests | length')" -eq 0 ]

Build requirements

Before tests can run, your application build must be uploaded to MobileBoost.

Simulators

Platform	Format	How to generate
Android	`.apk`	Build in Android Studio (Build > Build APK(s)) or via Gradle: `./gradlew assembleDebug`
iOS	`.zip` or `.tar.gz` containing the `.app` bundle	Build in Xcode targeting an iOS Simulator, then compress the `.app` folder

iOS simulator builds: Build your app in Xcode targeting an iOS Simulator. Locate the .app file at Product > Show Build Folder in Finder > Products/Debug-iphonesimulator. Then compress it:

zip -r MyApp.zip MyApp.app

Or build from the command line:

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -sdk iphonesimulator -configuration Debug

Physical devices

Platform	Format	Notes
Android	`.apk`	Same as simulator builds
iOS	`.ipa`	MobileBoost automatically re-signs the `.ipa` for the test device grid. No special certificates or provisioning profiles required on your end

Getting started

Test definitions

Test execution

Test reports

GitHub Action

Inputs

Required secrets

CI provider snippets

API

Step 1: Upload the build

Step 2: Start a run

Step 3: Get the results

Build requirements

Simulators

Physical devices

​GitHub Action

​Inputs

​Required secrets

​CI provider snippets

​API

​Step 1: Upload the build

​Step 2: Start a run

​Step 3: Get the results

​Build requirements

​Simulators

​Physical devices

GitHub Action

Inputs

Required secrets

CI provider snippets

API

Step 1: Upload the build

Step 2: Start a run

Step 3: Get the results

Build requirements

Simulators

Physical devices