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

# Apps

> Upload and manage your apps and websites in BugRadar

Before you can run any flows, you need to add your app or website to BugRadar.

[Apps](https://www.veed.io/embed/55955b5a-32ec-4966-b649-56467e83a026?watermark=0\&color=default\&sharing=0\&title=1)

## What is an App?

In BugRadar, an **app** represents something you want to test - this can be a mobile app (iOS or Android) or a website.

### Key Concepts

* **App**: A mobile application or website you want to test
* **Chrome Extension**: An optional dependency included in web flow runs
* **Build**: A specific version of your mobile app (.app for iOS, APK for Android, or a url for a website)
* **Default build**: The build tests run on unless a run picks a different one
* **Environment**: Optional grouping to organize apps (e.g., Development, Staging, Production)

## Creating a New App

### Step 1: Navigate to Apps Page

Click on **[Apps](https://usebugradar.com/apps)** in the sidebar navigation.

### Step 2: Click "Create New App"

Click the **Create New App** button in the top right corner.

### Step 3: Fill in App Details

**Required Fields:**

* **App Name**: A descriptive name for your app (e.g., "MyApp iOS")
* **Bundle ID**: Your app's unique identifier (e.g., `com.company.appname`)

**Optional Fields:**

* **App ID** (iOS and Android): Expand **App ID (optional)** to set one. Only needed to keep several apps with the same bundle ID in one environment, for example one per release version.
* **Environment**: Assign the app to an environment for better organization
* **Agent Context**: Add special instructions for the agent (e.g., "The app requires biometric authentication on first launch")

[Learn more about finding your Bundle ID →](/docs/bundle-id.md)

### Step 4: Select Platform and Upload

Choose your app's platform and provide the required build or URL:

> [tab] iOS
>
> **Upload Requirements:**
>
> * For simulator tests, upload a `.zip` containing an `.app` built for iOS Simulator
> * For physical-device tests, upload a Development or Ad Hoc signed `.ipa`
> * BugRadar routes `.zip` / `.app` builds to simulators and `.ipa` builds to real devices
> * Each iOS build on the Apps page and in the Run dialog is tagged **Simulator** or **Real device**. If an app has only `.ipa` builds, **Simulator** is greyed out in the Run dialog until you upload a `.app`
>
> When uploading an IPA whose Team-ID-prefixed Keychain access groups break
> after cloud re-signing, expand **Advanced** and enable **Fix Keychain access
> after re-signing**. Most apps do not need this option.
>
> [Learn more about simulator and real-device iOS builds →](/docs/app-build-guide.md)

> [tab] Android
>
> **Upload Requirements:**
>
> * Drag and drop an `.apk` file
> * Ensure the APK includes the `x86_64` architecture (universal APKs are recommended)
> * Every Android device includes Google Play services, so no extra setup is needed
>
> [Learn more about building Android apps →](/docs/app-build-guide.md#android-builds)

> [tab] Web
>
> **No build file required!**
>
> * Simply enter the URL of your website (e.g., `https://example.com`)
>
> Simply enter your website URL — no build files needed. When triggering a run you can choose between **Chrome** (real Google Chrome — default), **Firefox**, **Edge** (Microsoft Edge), or **Chromium** (open-source, no proprietary codecs / DRM).
>
> [See Web Testing for how each engine differs and when to pick which →](/docs/web-testing.md)

> [tab] Chrome Extension
>
> Add a Manifest V3 extension in either form:
>
> * Paste its Chrome Web Store URL to snapshot the current published version
> * Upload a `.zip` containing the unpacked extension directory
>
> Store registration derives the extension name and ID automatically. For a
> zip upload, enter a name; the Bundle ID is optional but recommended when CI
> will upload future versions of the same extension.
>
> Extension zips may contain `manifest.json` at the archive root or inside one
> top-level folder. The compressed archive limit is 500MB. Uploaded extension
> archives are stored privately and are only accessed when BugRadar runs your tests.
>
> Extensions are organization-wide dependencies, so they do not belong to an
> environment and cannot be run directly. Attach them from a web app's row or
> select them for one run in the Run dialog.

### Step 5: Complete Upload

Click **Upload** and wait for the file to upload. Once complete, your app will appear in the Apps list.

## Managing Builds

Each app can have many builds, so you can test new versions while keeping earlier ones available.

Each app is a row on the Apps page, grouped under its environment. The row shows the app's latest upload. Once an app has a build, click **N builds** (**N URLs** for a website, **N versions** for an extension) to list the 5 newest under the row. If there are more, **View all builds** (**View all URLs**, **View all versions**) opens every build in a side panel, where **Search branches** filters by branch name.

### Uploading a New Build

Click **Upload build** on the app's row (**Update URL** for a website, **Upload version** for an extension), choose the file, and click **Upload**.

### Default build

Tests run on the default build unless a run picks a different one. Each upload becomes the default.

To run tests on an older build instead, hover it in the builds list and click **Make default**. It stays the default until the next upload, and the row shows **Default build is pinned to …** so you know tests are not running on the newest upload.

### Build actions

Open a build's **⋯** menu for:

* **Build variables**: Set [build variables](/docs/variables.md#build-variables)
* **Download**: Download the build file (not for websites)
* **Delete build**: Remove the build. You can undo right after deleting.

> [!WARNING]
>
> If you delete the default build, the newest remaining build that didn't come from a device sandbox becomes the default. If none remains, the app has no default build until you upload one.

## Editing App Details

### Changing App Name

1. Hover the app name and click the pencil icon
2. Edit the name
3. Press **Enter** or click **Save**

### App menu

Open the app's **⋯** menu for:

* **Agent context**: Special instructions for the agent when running flows on this app. Enter them and click **Save**.
* **Change environment**: Move the app to another environment, or **No environment**
* **Copy app UUID**: Copy the UUID that the [Apps API](/docs/api-apps.md) and `BugRadar run --app-id` accept
* **Delete app**

**Example Agent context:**

```
This app uses Face ID on first launch.
The test account is test@example.com with password TestPass123.
After login, dismiss the tutorial overlay by tapping "Skip".
```

## Organizing with Environments

Environments help you organize apps by deployment stage or purpose.

### Creating an Environment

1. Navigate to **[Settings](https://usebugradar.com/settings)** → **Environments**
2. Click **Create Environment**
3. Enter a name (e.g., "Staging", "Production", "QA")
4. Click **Create**

### Assigning Apps to Environments

* **During app creation**: Select an environment from the dropdown
* **After creation**: Open the app's **⋯** menu and choose **Change environment**
* **Via CI/CD**: Pass the `environment` parameter in the [GitHub Action](/docs/ci-cd-integration.md#step-3-set-up-your-github-workflow-with-the-BugRadar-github-action) or [Upload API](/docs/api-ci.md) to automatically assign the app to an environment on upload

Apps grouped by environment appear in separate sections on the Apps page.

> [!TIP]
>
> If you have release and develop builds that share the same bundle ID, use different environments to keep them as separate apps. See [Assigning Apps to Environments](#assigning-apps-to-environments) above for setup instructions.

To keep several apps with the same bundle ID in one environment, for example one per release version, give each its own App ID. Set it when you create the app, on the app's row, or by uploading with an `app-id`. The app's row shows it next to the bundle ID. See [Separate apps that share a bundle ID](/docs/ci-cd-integration.md#separate-apps-that-share-a-bundle-id).

## Troubleshooting

### Common Issues

**iOS:**

* For simulator runs, ensure the `.zip` contains a valid simulator `.app`
* For physical-device runs, upload a Development or Ad Hoc signed `.ipa`
* Do not rename an IPA to `.zip`; the extension determines the target device type
* Verify the bundle ID matches what you entered

**Android:**

* Ensure the APK is properly signed
* Check that the file extension is `.apk`
* Verify the bundle ID matches the package name

**Chrome extensions:**

* Only Manifest V3 extensions are supported
* Upload a `.zip` of the unpacked extension, not a `.crx`
* Keep `manifest.json` at the archive root or inside one top-level folder
* Extension-enabled runs use Chrome (default) or Chromium

## Next Steps

Now that you've uploaded your app:

* [Create your first flow →](/docs/flows.md)
* [Set up our CI/CD integration →](/docs/ci-cd-integration.md)
* [Organize flows with suites →](/docs/suites.md)


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