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

# GitHub Actions

> Upload builds and run MobileBoost tests from GitHub Actions.

Use the MobileBoost GitHub Actions to upload a build and run your mobile tests from your CI pipeline:

* **`upload-build`** uploads your iOS or Android build (`.zip` or `.apk`).
* **`run-tests`** runs your tests against that build and reports pass or fail.

You do not need to install anything or use GitHub Marketplace. Reference the actions directly from `MobileBoostHQ/actions`.

## Add your credentials

In your repository, go to **Settings** > **Secrets and variables** > **Actions**.

In the **Secrets** tab, create a repository secret:

* `MOBILEBOOST_API_KEY`: Your MobileBoost API key, such as `mb_live_...`.

In the **Variables** tab, create a repository variable:

* `MOBILEBOOST_ORG_ID`: Your MobileBoost organization ID.

<Note>
  You can find your API key and organization ID in the MobileBoost dashboard.
  You can also ask your MobileBoost contact for them.
</Note>

## Add a workflow

Create `.github/workflows/mobileboost.yml` in your repository:

```yaml theme={null}
name: Mobile tests
on:
  push:
    branches: [main]

jobs:
  mobile-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Add your existing build steps that produce a .apk or .zip.

      - uses: MobileBoostHQ/actions/upload-build@v1
        id: upload
        with:
          api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
          organisation-id: ${{ vars.MOBILEBOOST_ORG_ID }}
          build-path: app/build/outputs/apk/release/*.apk

      - uses: MobileBoostHQ/actions/run-tests@v1
        with:
          api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
          organisation-id: ${{ vars.MOBILEBOOST_ORG_ID }}
          build-id: ${{ steps.upload.outputs.build-id }}
          tags: smoke
```

On each push, this workflow uploads your build, runs the tests tagged `smoke`, waits for them to finish, and fails the job if any test fails. The run summary includes a result table and recording links.

## Key inputs

### `upload-build`

| Input             | Required | Description                                                                                                    |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `api-key`         | Yes      | Your API key. Use the repository secret.                                                                       |
| `organisation-id` | Yes      | Your organization ID.                                                                                          |
| `build-path`      | Yes      | Path to a `.zip` or `.apk`, a directory that is zipped automatically, or a glob where the first match is used. |

Outputs:

* `build-id`: Pass this to `run-tests`.
* `app-link`: Dashboard URL.

### `run-tests`

| Input                  | Required                    | Description                                                                   |
| ---------------------- | --------------------------- | ----------------------------------------------------------------------------- |
| `api-key`              | Yes                         | Your API key. Use the repository secret.                                      |
| `organisation-id`      | Yes                         | Your organization ID.                                                         |
| `build-id`             | Yes                         | The `build-id` from the `upload-build` step output.                           |
| `tags`                 | One of `tags` or `test-ids` | Comma-separated tags. Runs tests matching any tag.                            |
| `test-ids`             | One of `tags` or `test-ids` | Comma-separated test IDs. Takes precedence over `tags`.                       |
| `async`                | No                          | Set to `true` to trigger the run without waiting. Defaults to `false`.        |
| `timeout-minutes`      | No                          | Maximum wait time in sync mode. Defaults to `60`.                             |
| `fail-on-test-failure` | No                          | Set to `false` to report results without failing the job. Defaults to `true`. |

<Note>
  Provide at least one of `tags` or `test-ids`. If both are provided, `test-ids` takes precedence.
</Note>

## Common variations

### Run specific tests with a shorter wait

```yaml theme={null}
- uses: MobileBoostHQ/actions/run-tests@v1
  with:
    api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
    organisation-id: ${{ vars.MOBILEBOOST_ORG_ID }}
    build-id: ${{ steps.upload.outputs.build-id }}
    test-ids: t_abc123,t_def456
    timeout-minutes: 30
```

### Trigger and inspect later

Set `async` to `true` to trigger the run without waiting for it to finish.

```yaml theme={null}
async: true
```

### Report results without failing the job

Set `fail-on-test-failure` to `false`.

```yaml theme={null}
fail-on-test-failure: false
```

### Run only on a merged pull request

Change the workflow trigger:

```yaml theme={null}
on:
  pull_request:
    types: [closed]
jobs:
  mobile-tests:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    # Use the same steps as above.
```

## Pin the version

* `@v1`: Recommended. Automatically gets the latest `v1.x.x` release with bug fixes and no breaking changes.
* `@v1.2.3`: Pins to an exact version for full reproducibility.
* `@main`: Tracks the latest commit. This may include breaking changes, so it is not recommended for production.

## Troubleshooting

| Symptom                                   | Fix                                                                                 |
| ----------------------------------------- | ----------------------------------------------------------------------------------- |
| `Invalid API key (401)`                   | Check that `MOBILEBOOST_API_KEY` is set and uses your `mb_live_...` key.            |
| `No file or directory matched build-path` | Make sure your build step ran and the path or glob is correct.                      |
| `Unsupported build file`                  | Only `.zip` and `.apk` files are supported.                                         |
| Run `did not finish within the timeout`   | Increase `timeout-minutes`, or use `async: true`. The run continues in MobileBoost. |
| Job fails with `N failed, M blocked`      | Tests failed. Open the dashboard link in the run summary to view recordings.        |

Behind a corporate proxy, the actions honor `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY`. They also support custom CA bundles via `NODE_EXTRA_CA_CERTS`.

Questions or issues? Contact your MobileBoost representative.