---
title: Submit an iOS Build for App Review
description: Distribute iOS builds to external TestFlight beta groups and submit them for App Review from Capawesome Cloud — prerequisites, destination settings, and how the submission works.
---

# Submit for App Review

Every submission to an [App Store Connect destination](destinations/apple-app-store.md) uploads the build to TestFlight. With an App Store Connect API key, the destination can go further: distribute the build to external TestFlight **beta groups** and submit it for **App Review**, so a single deployment takes a build from Capawesome Cloud to the App Store.

## Prerequisites

- **API key**: The destination must use the `API Key` authentication method. Destinations with an Apple ID and app-specific password can only upload to TestFlight. See [API Key Credentials](destinations/apple-app-store.md#api-key-credentials).
- **Export compliance**: Your app's `Info.plist` must declare `ITSAppUsesNonExemptEncryption`. Otherwise, the deployment fails before the upload with the message "Info.plist must declare ITSAppUsesNonExemptEncryption for TestFlight external distribution and App Store submission". Capawesome Cloud never answers Apple's export compliance question on your behalf. See Apple's guide on [complying with encryption export regulations](https://developer.apple.com/documentation/security/complying-with-encryption-export-regulations){:target="_blank"} to pick the right value. For example, an app that uses no non-exempt encryption declares:

    ```xml
    <key>ITSAppUsesNonExemptEncryption</key>
    <false/>
    ```

- **Test Information**: Beta App Review needs the **Test Information** of your app in App Store Connect under **TestFlight**, such as the contact details and a demo account if your app requires a sign-in. Fill it in once per app before the first distribution to a beta group.
- **App Store listing**: A submission only sets **What's New**. Screenshots, description, and all other metadata stay as they are in App Store Connect, so complete them there before your first submission.

## Configure the destination

The destination decides what happens after the upload:

- **Beta groups**: The external TestFlight beta groups to distribute the build to, up to 20. Enter the group names exactly as they appear in App Store Connect. See [Distribute to beta groups](#distribute-to-beta-groups).
- **Submit for App Review**: Submit the build for App Review after the upload. The build still goes to TestFlight first, so this option means TestFlight **and** the App Store, never the App Store only.
- **Release type**: Apple's version release setting for the submitted version. With `Manual` (default), you release the approved version yourself. With `After approval`, Apple releases it automatically once App Review approves it.
- **Cancel pending submission**: Cancel a submission that is waiting for review before submitting the new build.

=== "CLI"

    Set the options with [`apps:destinations:create`](../cli/commands.md#appsdestinationscreate) or [`apps:destinations:update`](../cli/commands.md#appsdestinationsupdate):

    ```bash
    npx @capawesome/cli apps:destinations:update --app-id <app-id> --destination-id <destination-id> \
      --apple-beta-group "External Testers" \
      --apple-submit-for-review \
      --apple-release-type after-approval \
      --apple-reject-if-possible
    ```

    `--apple-beta-group` can be repeated or take a comma-separated list. Pass `--apple-beta-group=` to remove all groups, and `--apple-submit-for-review false` or `--apple-reject-if-possible false` to turn the options off again. `--apple-release-type` accepts `manual` or `after-approval`.

=== "Console"

    Open the destination on the [Destinations](https://console.cloud.capawesome.io/apps/_/destinations){:target="_blank"} page. With the authentication method `API Key`, the dialog shows the **Beta groups** field and the **Submit for App Review** checkbox. **Release type** and **Cancel pending submission** appear once **Submit for App Review** is checked.

## Distribute to beta groups

Once Apple has processed an uploaded build, it is available in TestFlight to your internal groups with automatic distribution enabled, whatever the destination's settings. Other internal groups need the build assigned manually in App Store Connect, and external testers only receive it through the destination's beta groups.

With beta groups set, the deployment waits until Apple has processed the build, distributes it to the groups, and submits it for Beta App Review. Apple reviews the build asynchronously, so the deployment finishes before the review does, and your testers are notified once Apple has approved the build.

Deployments to a destination with beta groups require [release notes](release-notes.md), which become **What to Test** in TestFlight. Since [automations](submit-automatically.md) can't provide release notes, submit such builds with the CLI instead.

## How the submission works

With **Submit for App Review**, a deployment runs these steps:

1. Upload the build to TestFlight, with the default [release notes](release-notes.md) as **What to Test** when release notes are given.
2. If the destination has beta groups, wait until Apple has processed the build, distribute it to the groups, and submit it for Beta App Review.
3. Create the App Store version matching the build's version. If a version with a different number is currently editable in App Store Connect, for example one you prepared by hand, it is renamed to the build's version instead of creating a second one, since Apple allows only one editable version.
4. When release notes are given, write them to **What's New**: the default text for every language of the version, then each translation for its language. Provide translations only for the languages of your App Store listing, since a translation for another language creates a new localization of the version.
5. Wait until Apple has processed the build and attach it to the version.
6. Cancel a pending submission if **Cancel pending submission** is checked, then submit the version for App Review with the configured release type.

Apple typically needs 10 to 30 minutes to process a build. With beta groups or App Review submission, the deployment waits for this processing, and the waiting time counts toward your [build minutes](../native-builds/limits.md#build-minutes). Without them, the deployment finishes right after the upload.

Automations can submit for App Review too: attach the destination to an [automation](submit-automatically.md), and every matching tag is built, uploaded, and submitted. Their submissions carry no release notes, so **What's New** stays as it is in App Store Connect.

### First App Store version

Apple rejects **What's New** on the very first App Store version of an app. Release notes only fail when the destination submits for review, since TestFlight's What to Test is unaffected. Deploy the first version without release notes, and Capawesome Cloud submits it without **What's New**. Or use a destination with **Submit for App Review** turned off and submit the version in App Store Connect yourself. Later versions can carry release notes.

## After a failed submission

If the submission fails after the build was attached, the prepared version stays in App Store Connect. Fix the cause shown in the deployment logs, then submit the version in App Store Connect or deploy a new build, which reuses the editable version. See [Troubleshooting](troubleshooting.md) for the common errors.

## Next steps

- [Add release notes](release-notes.md) — What to Test for testers and What's New for the App Store.
- [App Store Connect destination](destinations/apple-app-store.md) — credentials and the destination's other settings.
- [Submit automatically after a build](submit-automatically.md) — submit every release tag for App Review with an automation.