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

# Github Action for App Uploads

> Automatically upload mobile builds or register web apps with BugRadar

Integrate BugRadar into your CI/CD pipeline with our GitHub Action to automatically upload and test your builds with every commit. Supports iOS, Android, web, and Chrome-extension platforms.

![BugRadar GitHub Action uploading a build](https://mintcdn.com/BugRadar/uDsFIKjlKiNoma8I/images/github-action-example.png?fit=max\&auto=format\&n=uDsFIKjlKiNoma8I\&q=85\&s=18c183667c3c8c384af482404418faa1)

> [!TIP]
>
> Add our [MCP Server](/docs/mcp-setup.md) to help with setting up your CI/CD pipeline.

## Step 1: Choose Your Platform

Select your platform to see the relevant setup instructions:

> [card] [iOS / Android](#mobile-setup)
>
> Mobile app builds (Expo, Fastlane, native)

> [card] [Web](#web-setup)
>
> Web apps (Vercel, Netlify, custom deployments, etc.)

> [card] [Chrome Extension](#chrome-extension-setup)
>
> Manifest V3 extension zip builds

***

## Mobile Setup

### Choose Your Build Tool

> [card] [Expo EAS](#expo-eas-ios)
>
> React Native with Expo's build service

> [card] [Fastlane](#fastlane-ios)
>
> Native iOS/Android builds with Fastlane

> [card] [Other](#native-ios)
>
> Gradle, Flutter, or custom builds

***

## Step 2: Set Secrets

Go to your repository **Settings → Secrets → Actions** and add these secrets. See the [GitHub Secrets docs](https://docs.github.com/en/actions/security-guides/encrypted-secrets) for help.

### Required for All

**BugRadar\_KEY** `string` *required*

Your BugRadar API key for uploading builds. Create one with `BugRadar keys create` or in [Settings → API Keys](https://usebugradar.com/settings?tab=api-keys).

### Required for Expo EAS

**EXPO\_TOKEN** `string`

Your Expo access token for EAS builds. Get it from [Expo account settings](https://expo.dev/accounts/\[account]/settings/access-tokens).

***

## Step 3: Set up your Github Workflow with the BugRadar Github Action

Create a `.github/workflows/BugRadar-ios.yml` and/or `.github/workflows/BugRadar-android.yml` file in your repository. Examples are provided below to get started.

> [!NOTE]
>
> For more specific build instructions by framework, check out our [App Build Guide](/docs/app-build-guide.md) for detailed instructions on creating builds for iOS and Android.

Add this step to your existing GitHub workflow after your build step:

```yaml theme={null}
- name: Upload to BugRadar
  uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    bundle-id: com.your.app  # Replace with your app's bundle ID
    platform: ios  # or 'android'
    build-path: ./path/to/your/build.ipa  # iOS: .ipa or zipped .app | Android: .apk
    # labels: smoke,critical  # Optional: run everything carrying these labels
    # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
    # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
    # suite-keys: smoke  # Optional: run a code-managed suite by its YAML key
    # flow-keys: auth/login,checkout  # Optional: run code-managed flows by YAML key
    # environment: staging  # Optional: separate apps by environment
    # variables: TEST_ACCOUNT=qa-smoke,CHECKOUT_VARIANT=control  # Optional: attach build variables
    # enable-ios-keychain-access-group-remapping: true  # Optional: IPA re-signing compatibility
```

> [!NOTE]
>
> **Required Parameters:**
>
> * `api-key`: Your BugRadar API key (from secrets)
> * `bundle-id`: Your app's bundle ID (e.g., `com.company.app`)
> * `platform`: Either `ios` or `android`
> * `build-path`: Path to your build artifact. Optional when the step selects tests: leave it empty to [run tests without uploading](#run-tests-on-more-devices-with-one-upload).
>
> **Optional Parameters:**
>
> * `name`: Display name for your app (e.g., "My iOS App"). Updates existing app name if different.
> * `app-id`: Custom identifier that keeps several apps with the same bundle ID in one environment (e.g., `v7.12.0`). See [Separate apps that share a bundle ID](#separate-apps-that-share-a-bundle-id) below.
> * `labels`: Comma-separated label names to run after upload (e.g., `smoke,critical`). Runs every suite and flow carrying any of the labels — resolved at run time, so CI config never changes as coverage grows. See [Labels API](/docs/api-labels.md#run-by-label).
> * `suite-ids`: Comma-separated suite UUIDs to run after upload (e.g., `uuid1,uuid2`).
> * `flow-ids`: Comma-separated flow UUIDs to run after upload (e.g., `uuid1,uuid2`).
> * `suite-keys`: Comma-separated [code-managed](/docs/code-managed-flows.md) suite keys to run from the checked-out commit.
> * `flow-keys`: Comma-separated [code-managed](/docs/code-managed-flows.md) flow keys to run from the checked-out commit.
> * `folder-ids`: Comma-separated [folder](/docs/flows.md#running-a-folder) UUIDs to run after upload. Copy one from the folder's **⋯** menu on the Flows page (**Copy folder ID**). Runs every suite and flow in the folder and its subfolders.
> * `folder-paths`: Comma-separated [code-managed](/docs/code-managed-flows.md) folder paths below `.BugRadar/`, such as `Auth/Onboarding`, to run from the checked-out commit.
> * `environment`: Name of the environment to associate this app with (e.g., `staging`, `production`). See [Assigning apps to environments](/docs/apps.md#assigning-apps-to-environments).
> * `location`: Android emulator runs only. Two-letter country code, such as `MX`, that every run this upload starts sends its traffic from. iOS uploads and physical devices are refused. See [Run from another country](#run-from-another-country).
> * `locale`: Language and region, such as `de-DE`, that every run this upload starts opens the app in. Android and iOS. See [Run in another language](#run-in-another-language).
> * `variables`: Key-value variables to attach to the uploaded build. Available in flow instructions via `${env:KEY}`. Use `KEY1=VALUE1,KEY2=VALUE2`. See [Build Variables](/docs/variables.md#build-variables).
> * `physical-device`: Mobile runs only. Set to `true` to use real hardware; defaults to `false`.
> * `device-model`: Mobile runs only. Model from the BugRadar device catalog, such as `Pixel 10 Pro`, or `latest`. Two-device flows use it for both devices.
> * `os-version`: Mobile runs only. OS version supported by the selected model, such as `17`, or `latest`. Two-device flows use it for both devices.
> * `model-match`: Real devices only. `similar` (default) lets a busy pinned model fall back to a similar free model; `exact` keeps that model.
> * `os-version-match`: Real devices only. `similar` (default) lets a busy pinned OS fall back to a nearby version; `exact` keeps that version.
> * `devices`: Mobile runs only. JSON array of exactly two ordered device selections, used instead of `physical-device`, `device-model`, `os-version`, `model-match`, and `os-version-match` to choose each device of a two-device flow. One-device flows in the same run use the first entry.
> * `dependencies`: For direct web runs only, a JSON array overriding the web app's default Chrome extension loadout. Omit it to inherit defaults, use `'[]'` for no extensions, or provide extension app UUIDs and optional build pins. Requires `suite-ids`, `flow-ids`, `folder-ids`, `flow-keys`, or `labels`. It cannot be combined with `suite-keys` or `folder-paths`.
> * `wait`: Whether to wait for selected tests and fail the job when they fail. Defaults to `true`; set it to `false` for fire-and-forget runs.
> * `enable-ios-keychain-access-group-remapping`: iOS `.ipa` only. Set to `true` if cloud re-signing breaks Team-ID-prefixed Keychain access groups. The preference is saved on the app, so future IPA uploads can omit it; set it to `false` to disable.

### Snoozed tests

The Action skips [snoozed](/docs/flows.md#snoozing-a-test) tests, except when it runs exactly one test by `flow-ids` or `flow-keys`. A snoozed test does not fail the job:

* The trigger line counts them: `Triggered 4 flow(s) (1 snoozed)`.
* Each one is listed as `☾ <name> SNOOZED`.
* When every selected test is snoozed, the job passes with `✅ 0 ran, all N snoozed.`, also with `wait: false`.

Other skipped tests, such as ones whose suite setup failed, still fail the job.

### Run code-managed tests by key

Use stable YAML keys instead of BugRadar UUIDs when your flows and suites are
[managed in code](/docs/code-managed-flows.md). The Action resolves each key from the
exact checked-out commit:

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: android
    bundle-id: com.example.app
    build-path: build/app-release.apk
    flow-keys: auth/login,checkout
    suite-keys: smoke
    folder-paths: Auth/Onboarding
```

You can combine `flow-keys`, `suite-keys`, and `folder-paths`. A folder path runs
every suite and flow in that directory of `.BugRadar/` and the directories inside
it. Suites and flows made in the dashboard and filed in that folder also run, as
saved. Do not combine these with `flow-ids`, `suite-ids`, `folder-ids`, or `labels`.

### Select a mobile device

Device inputs apply when any flow, suite, folder, or label selector triggers tests. Use
`latest` to make rolling model and OS selection explicit:

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: android
    bundle-id: com.example.app
    build-path: build/app-release.apk
    suite-ids: "suite-uuid"
    physical-device: false
    device-model: latest
    os-version: latest
```

You can pin either field while leaving the other on `latest`, or pin both to a
supported catalog combination:

```yaml theme={null}
    physical-device: false
    device-model: Pixel 10 Pro
    os-version: "17"
```

Omitting `device-model` and `os-version` keeps the same rolling-Latest behavior.
For the latest available real device, set `physical-device: true` and use
`latest` (or omission) for the model and OS.

On a real device, a pinned model that's busy falls back to the closest free
device. Set `model-match` or `os-version-match` to `exact` to keep that field
fixed. For example, any free phone on iOS 26, preferring iPhone 16 Pro:

```yaml theme={null}
    physical-device: true
    device-model: iPhone 16 Pro
    os-version: "26"
    os-version-match: exact
```

### Run tests on more devices with one upload

When several jobs test the same build on different devices, let one job upload
the build and leave `build-path` empty in the others. A job without
`build-path` skips the upload and runs its tests on the build already uploaded
for the same commit, in the same app (bundle ID, platform, `environment`, and
`app-id`).

```yaml theme={null}
jobs:
  build:
    runs-on: macos-latest
    steps:
      # ... build build/MyApp.app.zip ...
      - uses: actions/upload-artifact@v4
        with:
          name: ios-build
          path: build/MyApp.app.zip

  test:
    needs: build # start testing only once the build exists
    runs-on: ubuntu-latest
    strategy:
      matrix:
        device:
          - { model: "iPhone 17 Pro", upload: true }
          - { model: "iPad Pro 13-inch (M5)" }
    steps:
      - uses: actions/download-artifact@v4
        if: matrix.device.upload
        with:
          name: ios-build
          path: build
      - uses: BugRadar/BugRadar-ci@main
        with:
          api-key: ${{ secrets.BugRadar_KEY }}
          platform: ios
          bundle-id: com.example.app
          build-path: ${{ matrix.device.upload && 'build/MyApp.app.zip' || '' }}
          device-model: ${{ matrix.device.model }}
          labels: smoke
```

Build the app in its own job and make the test jobs wait for it with `needs:`,
as above. The other jobs then wait only for the upload, not the build: up to 10 minutes from when the action starts, then they
fail with `No build for commit <sha>`. If the commit already has a build,
for example from an earlier run of the workflow, the job uses that build at
once. `name` and `enable-ios-keychain-access-group-remapping` apply only to
uploads, so a step without `build-path` ignores them. It must
select tests with `labels`, `suite-ids`, `flow-ids`, `folder-ids`,
`suite-keys`, `flow-keys`, or `folder-paths`.

### Separate apps that share a bundle ID

By default, every build with the same bundle ID and platform in an environment
goes to one app. Set `app-id` to keep them apart, for example one app per
release version:

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: android
    bundle-id: com.example.app
    app-id: v7.12.0
    build-path: build/app-release.apk
    suite-ids: "suite-uuid"
```

The first upload with a new `app-id` creates the app, named after the
`app-id` unless you also set `name`. Later uploads with the same `app-id` add
builds to it, and any tests the step triggers run against that app. All of
these apps share the environment's variables.

`app-id` can be up to 64 characters: lowercase letters, numbers, dots, hyphens,
and underscores. It must start and end with a letter or number, with no two
separators in a row. Automations are set up per app, so a new app starts with none.
Trigger its tests from this step with `suite-ids`, `flow-ids`, or `labels`.

### Github Action Workflow Examples

> [tab] Expo EAS (iOS)
>
> ### Configure eas.json
>
> Add this profile to your `eas.json` for iOS simulator builds:
>
> ```json eas.json theme={null}
> {
>   "build": {
>     "preview-simulator": {
>       "distribution": "internal",
>       "ios": {
>         "simulator": true
>       }
>     }
>   }
> }
> ```
>
> ### GitHub Workflow
>
> > [!WARNING]
> >
> > **Important:** Replace `YOUR_BUNDLE_ID` with your app's bundle ID.
>
> ```yaml .github/workflows/BugRadar-eas-ios.yml theme={null}
> name: EAS iOS Simulator Build + BugRadar
>
> on:
>   # Triggers on pushes to main branch (including merges)
>   push:
>     branches:
>       - main
>   # Allows for manual triggering of the workflow from the GitHub UI.
>   workflow_dispatch:
>
> jobs:
>   build-and-test:
>     runs-on: ubuntu-latest
>
>     steps:
>       # Step 1: Check out the repository's code
>       - name: Checkout repository
>         uses: actions/checkout@v4
>
>       # Step 2: Set up Node.js
>       - name: Set up Node.js
>         uses: actions/setup-node@v4
>         with:
>           node-version: '18'
>           cache: 'npm'
>
>       # Step 3: Set up Expo and EAS
>       - name: Set up Expo and EAS
>         uses: expo/expo-github-action@v8
>         with:
>           eas-version: latest
>           token: ${{ secrets.EXPO_TOKEN }}
>
>       # Step 4: Install project dependencies
>       - name: Install dependencies
>         run: npm install
>
>       # Step 5: Run the EAS Build for an iOS Simulator
>       - name: Run iOS Simulator Build
>         run: eas build --platform ios --profile preview-simulator --non-interactive --wait --json > build-info.json
>
>       # Step 6: Download the .app artifact from the completed EAS build
>       - name: Download zipped .app from EAS
>         run: |
>           BUILD_URL=$(jq -r '.[0].artifacts.buildUrl' build-info.json)
>           echo "Downloading zipped .app from $BUILD_URL"
>           curl -L "$BUILD_URL" -o app.zip
>
>       # Step 7: Run the BugRadar CI action for testing
>       - name: Run BugRadar CI
>         uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: YOUR_BUNDLE_ID # TODO: Make sure this matches your app's bundle ID
>           platform: ios
>           build-path: app.zip
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

> [tab] Expo EAS (Android)
>
> ### Configure eas.json
>
> Add this profile to your `eas.json` for Android emulator builds:
>
> ```json eas.json theme={null}
> {
>   "build": {
>     "preview": {
>       "distribution": "internal",
>       "android": {
>         "buildType": "apk"
>       }
>     }
>   }
> }
> ```
>
> ### GitHub Workflow
>
> > [!WARNING]
> >
> > **Important:** Replace `YOUR_BUNDLE_ID` with your app's bundle ID.
>
> ```yaml .github/workflows/BugRadar-eas-android.yml theme={null}
> name: EAS Android Build + BugRadar
>
> on:
>   push:
>     branches:
>       - main
>   workflow_dispatch:
>
> jobs:
>   build-and-test:
>     runs-on: ubuntu-latest
>
>     steps:
>       - name: Checkout repository
>         uses: actions/checkout@v4
>
>       - name: Set up Node.js
>         uses: actions/setup-node@v4
>         with:
>           node-version: '18'
>           cache: 'npm'
>
>       - name: Set up Expo and EAS
>         uses: expo/expo-github-action@v8
>         with:
>           eas-version: latest
>           token: ${{ secrets.EXPO_TOKEN }}
>
>       - name: Install dependencies
>         run: npm install
>
>       - name: Run Android Build
>         run: eas build --platform android --profile preview --non-interactive --wait --json > build-info.json
>
>       - name: Download APK from EAS
>         run: |
>           BUILD_URL=$(jq -r '.[0].artifacts.buildUrl' build-info.json)
>           echo "Downloading APK from $BUILD_URL"
>           curl -L "$BUILD_URL" -o app.apk
>
>       - name: Run BugRadar CI
>         uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: YOUR_BUNDLE_ID # TODO: Replace with your bundle ID
>           platform: android
>           build-path: app.apk
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

> [tab] Fastlane (iOS)
>
> > [!WARNING]
> >
> > **Important:** Replace `com.example.app` with your app's bundle ID.
>
> ```yaml .github/workflows/BugRadar-fastlane-ios.yml theme={null}
> name: Fastlane iOS + BugRadar
>
> on:
>   push:
>     branches: [ main ]
>
> jobs:
>   build-and-test:
>     runs-on: macos-latest
>
>     steps:
>       - uses: actions/checkout@v4
>
>       - name: Set up Ruby
>         uses: ruby/setup-ruby@v1
>         with:
>           ruby-version: '3.0'
>           bundler-cache: true
>
>       - name: Build with Fastlane
>         run: bundle exec fastlane ios build_for_testing
>
>       - uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: com.example.app # TODO: Replace with your bundle ID
>           platform: ios
>           build-path: ./build/MyApp.app
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

> [tab] Fastlane (Android)
>
> > [!WARNING]
> >
> > **Important:** Replace `com.example.app` with your app's bundle ID.
>
> ```yaml .github/workflows/BugRadar-fastlane-android.yml theme={null}
> name: Fastlane Android + BugRadar
>
> on:
>   push:
>     branches: [ main ]
>
> jobs:
>   build-and-test:
>     runs-on: ubuntu-latest
>
>     steps:
>       - uses: actions/checkout@v4
>
>       - name: Set up JDK
>         uses: actions/setup-java@v3
>         with:
>           java-version: '11'
>           distribution: 'temurin'
>
>       - name: Set up Ruby
>         uses: ruby/setup-ruby@v1
>         with:
>           ruby-version: '3.0'
>           bundler-cache: true
>
>       - name: Build with Fastlane
>         run: bundle exec fastlane android build
>
>       - uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: com.example.app # TODO: Replace with your bundle ID
>           platform: android
>           build-path: ./app/build/outputs/apk/release/app-release.apk
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

> [tab] Native iOS
>
> > [!WARNING]
> >
> > **Important:**
> >
> > * Replace `com.example.app` with your app's bundle ID
> > * Replace the build command with your specific build process
> > * Update the build path to match your build output
>
> ```yaml .github/workflows/BugRadar-custom-ios.yml theme={null}
> name: Build and Upload to BugRadar (iOS)
>
> on:
>   push:
>     branches: [ main ]
>
> jobs:
>   build-and-upload:
>     runs-on: macos-latest  # iOS builds require macOS
>     steps:
>       - uses: actions/checkout@v4
>
>       # TODO: Build your iOS app
>       # Examples:
>       # - xcodebuild -workspace App.xcworkspace -scheme App -configuration Release
>       # - flutter build ios --release --no-codesign
>       # - react-native run-ios --configuration Release
>
>       - uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: com.example.app # TODO: Replace with your app's bundle ID
>           platform: ios
>           build-path: build/ios/iphoneos/MyApp.app # TODO: Update path
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

> [tab] Native Android
>
> > [!WARNING]
> >
> > **Important:**
> >
> > * Replace `com.example.app` with your app's bundle ID
> > * Replace the build command with your specific build process
> > * Update the build path to match your build output
>
> ```yaml .github/workflows/BugRadar-custom-android.yml theme={null}
> name: Build and Upload to BugRadar (Android)
>
> on:
>   push:
>     branches: [ main ]
>
> jobs:
>   build-and-upload:
>     runs-on: ubuntu-latest
>     steps:
>       - uses: actions/checkout@v4
>
>       # TODO: Build your Android app
>       # Examples:
>       # - ./gradlew assembleRelease
>       # - flutter build apk --release
>       # - react-native run-android --variant=release
>
>       - uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           bundle-id: com.example.app # TODO: Replace with your app's bundle ID
>           platform: android
>           build-path: app/build/outputs/apk/release/app-release.apk # TODO: Update path
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

***

## Chrome Extension Setup

Build or package the unpacked Manifest V3 extension directory as a `.zip`, then
upload it like a mobile build:

```yaml theme={null}
- name: Upload extension to BugRadar
  uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: chrome-extension
    bundle-id: my-wallet-extension
    name: My Wallet Extension
    build-path: ./dist/extension.zip
```

The first upload creates the extension; later uploads with the same
`bundle-id` create new versions and make the newest build active. Extension
apps are organization-wide and do not use `environment`.

The zip must contain `manifest.json` at its root or inside one top-level folder.
Only Manifest V3 is supported. Limits are 500MB compressed, 2GB expanded, and
25,000 entries.

After upload, attach the extension to a web app in the BugRadar Apps page.
CI-triggered tests inherit that app's default extensions.

> [!WARNING]
>
> Chrome extension upload steps cannot trigger tests directly. Do not add
> flow, suite, folder, or label selectors to a `platform: chrome-extension` step.
> Upload and attach the extension first, then run tests in a separate
> `platform: web` Action step using the web app's default extensions or a
> `dependencies` override.

***

## Web Setup

For web applications, you can register a URL (such as a preview deployment) for testing. This is useful for testing Vercel, Netlify, or other preview deployments on every PR.

To reuse cached navigation across preview deployments, also pass the deployment origin as a build variable named `BASE_URL`. The `url` input selects the launch URL; it does not create this variable automatically. The variable must contain only an HTTP(S) origin (an optional trailing `/` is allowed), without a path, query string, fragment, or credentials. See [Run Caching](/docs/flows.md#run-caching) for eligibility and live-execution limits. Keep production and preview targets in separate BugRadar environments.

### Parameters

> [!NOTE]
>
> **Required Parameters for Web:**
>
> * `api-key`: Your BugRadar API key (from secrets)
> * `platform`: Must be `web`
> * `app-id`: A unique identifier for your web app (lowercase, alphanumeric with hyphens, e.g., `my-web-app`)
> * `url`: The URL to test (e.g., your preview deployment URL)
>
> **Optional Parameters:**
>
> * `name`: Display name for your web app (e.g., "My Web App"). Updates existing app name if different.
> * `labels`: Comma-separated label names to run after upload (e.g., `smoke,critical`). Runs every suite and flow carrying any of the labels — resolved at run time, so CI config never changes as coverage grows. See [Labels API](/docs/api-labels.md#run-by-label).
> * `suite-ids`: Comma-separated suite UUIDs to run after upload (e.g., `uuid1,uuid2`).
> * `flow-ids`: Comma-separated flow UUIDs to run after upload (e.g., `uuid1,uuid2`).
> * `suite-keys`: Comma-separated [code-managed](/docs/code-managed-flows.md) suite keys to run from the checked-out commit.
> * `flow-keys`: Comma-separated [code-managed](/docs/code-managed-flows.md) flow keys to run from the checked-out commit.
> * `folder-ids`: Comma-separated [folder](/docs/flows.md#running-a-folder) UUIDs to run after upload. Copy one from the folder's **⋯** menu on the Flows page (**Copy folder ID**). Runs every suite and flow in the folder and its subfolders.
> * `folder-paths`: Comma-separated [code-managed](/docs/code-managed-flows.md) folder paths below `.BugRadar/`, such as `Auth/Onboarding`, to run from the checked-out commit.
> * `environment`: Name of the environment to associate this app with (e.g., `staging`, `production`). See [Assigning apps to environments](/docs/apps.md#assigning-apps-to-environments).
> * `location`: Two-letter country code, such as `MX`, that every run this upload starts sends its traffic from. See [Run from another country](#run-from-another-country).
> * `locale`: Language and region, such as `de-DE`, that every run this upload starts opens the browser in. See [Run in another language](#run-in-another-language).
> * `variables`: Key-value variables to attach to the registered build. Available in flow instructions via `${env:KEY}`. Use `KEY1=VALUE1,KEY2=VALUE2`. See [Build Variables](/docs/variables.md#build-variables).

### Basic Usage

```yaml theme={null}
- name: Register Web App with BugRadar
  uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: web
    app-id: my-web-app
    url: https://my-app-preview.vercel.app
    name: My Web App  # Optional: display name for the app
    # labels: smoke,critical  # Optional: run everything carrying these labels
    # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
    # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
    # suite-keys: smoke  # Optional: run a code-managed suite by its YAML key
    # flow-keys: auth/login,checkout  # Optional: run code-managed flows by YAML key
    # variables: DEPLOY_URL=${{ steps.deploy.outputs.url }},LOGIN_VARIANT=passwordless  # Optional: attach build variables
```

### Run from another country

Set `location` to a two-letter country code. Every run the upload starts sends its traffic from that country: the tests this step selects, your CI/CD automations (in place of the automation's own location), and later PR test runs against the build.

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: web
    app-id: my-web-app
    url: https://my-app-preview.vercel.app
    location: MX
    labels: smoke
```

For Android, set it on the upload step:

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: android
    bundle-id: com.example.app
    build-path: build/app-release.apk
    location: MX
    labels: smoke
```

It works for web runs and Android emulator runs. An iOS upload with a location is refused, and so is a run on a physical device. See [Proxy location](/docs/run-location.md). To change the language the app shows instead, see [Run in another language](#run-in-another-language).

### Run in another language

Set `locale` to a language and region, such as `de-DE`. Every run the upload starts opens the app in that language: the tests this step selects, your CI/CD automations (in place of the automation's own language), and later PR test runs against the build. It works on web, Android and iOS.

```yaml theme={null}
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    platform: android
    bundle-id: com.example.app
    build-path: build/app-release.apk
    locale: de-DE
    labels: smoke
```

See [Language & region](/docs/language-and-region.md).

### Override Chrome Extensions for a Web Run

The `dependencies` input controls the extension loadout for tests triggered
directly by this Action. It supports ID selectors, labels, and `flow-keys`, but
cannot currently be combined with `suite-keys`:

```yaml theme={null}
# Omit dependencies to inherit the web app's configured defaults.
labels: smoke

# Explicitly run with no extensions.
dependencies: '[]'

# Use one extension's active build and pin another extension to a specific build.
dependencies: >-
  ["11111111-1111-1111-1111-111111111111",
   {"app_id":"22222222-2222-2222-2222-222222222222",
    "app_build_id":"33333333-3333-3333-3333-333333333333"}]
```

Each string is an extension app UUID. Object entries use `app_id` and may add
`app_build_id` to pin an exact build. The input must be a valid JSON array and
is rejected for iOS, Android, and Chrome extension uploads.

### Web Workflow Examples

> [tab] Vercel
>
> For Vercel deployments using the GitHub integration (OAuth), use the `wait-for-vercel-preview` action to get the preview URL:
>
> ```yaml .github/workflows/BugRadar-web-vercel.yml theme={null}
> name: Web App Testing with BugRadar
>
> on:
>   pull_request:
>     branches: [ main ]
>
> jobs:
>   test-preview:
>     runs-on: ubuntu-latest
>     permissions:
>       contents: read
>       pull-requests: read
>       deployments: read
>
>     steps:
>       - name: Wait for Vercel Preview
>         uses: patrickedqvist/wait-for-vercel-preview@v1.3.2
>         id: vercel
>         with:
>           token: ${{ secrets.GITHUB_TOKEN }}
>           max_timeout: 600
>
>       - name: Register with BugRadar
>         uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           platform: web
>           app-id: my-web-app  # Choose a unique identifier for your app
>           url: ${{ steps.vercel.outputs.url }}
>           variables: BASE_URL=${{ steps.vercel.outputs.url }}
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```
>
> > [!NOTE]
> >
> > The `wait-for-vercel-preview` action requires the `permissions` block shown above to access deployment information. Without these permissions, you may see "Resource not accessible by integration" errors.
>
> > [!NOTE]
> >
> > The `app-id` must be lowercase alphanumeric with hyphens only (e.g., `my-web-app`, `staging`, `preview-app-123`). This identifier is used to track your web app across deployments.

> [tab] Custom / Static URL
>
> If you have a static staging URL or custom deployment:
>
> ```yaml .github/workflows/BugRadar-web-custom.yml theme={null}
> name: Web App Testing with BugRadar
>
> on:
>   push:
>     branches: [ main ]
>
> jobs:
>   test:
>     runs-on: ubuntu-latest
>
>     steps:
>       - name: Register with BugRadar
>         uses: BugRadar/BugRadar-ci@main
>         with:
>           api-key: ${{ secrets.BugRadar_KEY }}
>           platform: web
>           app-id: my-staging-app
>           url: https://staging.myapp.com
>           # labels: smoke,critical  # Optional: run everything carrying these labels
>           # suite-ids: uuid1,uuid2  # Optional: trigger suites after upload
>           # flow-ids: uuid1,uuid2  # Optional: or specify individual flows
> ```

***

## Step 4: What Happens Next?

Once you've set up our CI/CD integration:

**1. Run flows directly (optional)**

Add a flow, suite, folder, or label selector to your action config to trigger tests immediately after upload. For code-managed tests, use `flow-keys`, `suite-keys`, or `folder-paths` so the workflow keeps stable YAML identifiers instead of BugRadar UUIDs. The Action waits for all tests to complete and reports results inline, failing the job if any test fails. [Snoozed tests](#snoozed-tests) are skipped and don't fail it.

**2. Configure automations**

Alternatively (or additionally), set when flows run in your [Automations](https://usebugradar.com/automations) page to run flows on a schedule or trigger.

**3. View test results**

Check your test runs in the [Runs](https://usebugradar.com/runs) page.

***

## Need Help Setting Up?

If you're using Claude Code or another AI agent, you can add our MCP server to help automate the setup process. The MCP server can:

* Set up your CI/CD pipeline automatically
* Build your app for iOS or Android
* Find your app's bundle ID
* And more!

Learn more at our [MCP Server documentation](/docs/mcp-setup.md).

### Instructions for AI Agents Using the BugRadar MCP (humans, you can ignore this!)

> [!NOTE]
>
> If you are an AI agent (such as Claude Code, Cline, or Cursor) using the BugRadar MCP server to help set up CI/CD workflows, use the following prompt to guide your workflow generation.

```
Scan the repo to understand the project and how it is built. You should determine things like:
1. The project type (react-native, flutter, android-native, ios-native, etc)
2. Supported platforms (android, ios, or both)
3. Existing Github workflow files, if any
4. The correct build commands and configurations, indicated by the presence of Fastlane, EAS, etc... It can also help to look for .md files that explain the build process.
5. Available environments (development, staging, production, etc) and how they are configured

Create a plan for how to build the app. Then, generate a complete BugRadar-ios.yml and BugRadar-android.yml (whatever platforms are applicable) file, in .github/workflows. Use the best approach for the project (Fastlane, EAS, native, etc).

Unless specified otherwise by the user, the file(s) should start with the following:
name: BugRadar (platform) App Upload
on:
  workflow_dispatch:
  push:
    branches:
      - (primary branch)
  pull_request:
    branches:
      - (primary branch)

The file MUST contain the following BugRadar Github Actions script at the end:
- uses: BugRadar/BugRadar-ci@main
  with:
    api-key: ${{ secrets.BugRadar_KEY }}
    bundle-id: com.example.app # TODO: Replace with your bundle ID
    platform: ios/android
    build-path: ./build/MyApp.app # TODO: Replace with your build path

Important requirements:
- For Android, the APK must include the `x86_64` architecture; a universal APK is recommended
- For iOS, always build for simulator, not a real device
- Include actual paths based on common conventions for the detected framework
- Prefer the staging environment, if available (and not specified otherwise by the user)
- For EAS iOS builds, you can use a linux runner if doing cloud builds

Finally, once implemented, thoroughly review the script(s) to ensure it is correct before it's run.
It is critical that the script(s) will run successfully.
```

***

## Helpful Resources

> [card] [App Build Guide](/docs/app-build-guide.md)
>
> Learn how to build your app for our cloud

> [card] [GitHub Action](https://github.com/BugRadar/BugRadar-ci)
>
> View the source code and documentation for our GitHub Action

> [card] [Get Your API Key](https://usebugradar.com/settings?tab=integrations)
>
> Copy your API key from Settings → Integrations

### Commit detection and PR results

For `deployment` and `deployment_status` events, the action automatically uses the deployed commit, even when the workflow checks out trusted code. PR events continue to use the PR head SHA; other events retain checkout-based detection. For manual or scheduled workflows targeting a different commit from the checkout, pass `commit-sha` explicitly. Optional `branch-name` and `repo-full-name` inputs override the corresponding GitHub metadata. Web tests use the build returned by registration, keeping concurrent preview runs separate.

The action reports its result through the workflow job. To show that result on a different PR, the calling workflow must create and complete a check on the PR's head SHA with `checks: write` permission.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.