> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobileboost.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CI integration

> Upload builds and trigger tests from your CI/CD pipeline

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

## GitHub Action

The <a href="https://github.com/MobileBoostHQ/mobile-test-action" target="_blank">MobileBoost Test Action</a> uploads your build and sends the PR body (which should contain test instructions) to MobileBoost in a single step.

```yaml theme={null}
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](/test-agent/natural-language#format-requirements) in the Natural language test definitions page.

### 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`.

<Note>
  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.
</Note>

<Tabs>
  <Tab title="Bitrise">
    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.

    ```bash theme={null}
    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
    ```
  </Tab>

  <Tab title="GitLab CI">
    Add an `upload` stage to your `.gitlab-ci.yml` pipeline:

    ```yaml theme={null}
    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}"
    ```
  </Tab>

  <Tab title="CircleCI">
    Add an `upload-build` job to your `.circleci/config.yml`:

    ```yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="Jenkins">
    Add an **Upload Build** stage to your `Jenkinsfile`:

    ```groovy theme={null}
    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"
            }
        }
    }
    ```
  </Tab>
</Tabs>

## API

For full control, use the API directly. The process has two steps: upload the build, then trigger tests.

### Step 1: Upload the build

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

```bash theme={null}
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: Trigger tests

Use the `buildId` from step 1 to trigger test executions via `POST /tests/execute`.

**Run specific tests by ID:**

```json theme={null}
{
  "organisationId": "org123",
  "uploadId": "BUILD_ID_FROM_STEP_1",
  "testIds": ["test_abc", "test_def"]
}
```

**Run tests by tags:**

* Use `tags` for **OR** logic: runs tests with *at least one* matching tag
* Use `tagsQuery` for **AND** logic: e.g., `"AND(critical, android)"` runs tests that have *all* specified tags

```json theme={null}
{
  "organisationId": "org123",
  "platform": "android",
  "tagsQuery": "AND(critical, android)"
}
```

**Provide test input values:**

```json theme={null}
{
  "organisationId": "org123",
  "platform": "android",
  "tags": ["critical"],
  "testInputs": {
    "test_abc": {
      "email": "test@example.com"
    }
  }
}
```

## 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                  |

<Tip>
  **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:

  ```bash theme={null}
  zip -r MyApp.zip MyApp.app
  ```

  Or build from the command line:

  ```bash theme={null}
  xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -sdk iphonesimulator -configuration Debug
  ```
</Tip>

### 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 |