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

# Ship your iOS app to TestFlight

> Build your iOS app in the cloud and upload it to TestFlight from the Ship to TestFlight card in your chat.

In Newly v2, at app.newly.app and in Newly for Mac, you publish an iOS build from inside a chat. You ask the agent, a **Ship to TestFlight** card opens, and Newly builds your app on a cloud Mac and uploads it to App Store Connect. From there, TestFlight lets you install the app on your own iPhone and share it with testers.

## Before you start

You need all of these:

* **An Apple Developer Program membership.** Newly signs and uploads the app under your Apple team.
* **The organization owner or admin role.** Only an owner or admin can connect Apple and start an upload. Members see "An organization owner or admin must connect Apple and authorize the upload."
* **A saved Newly cloud project.** Publishing works from a Remote chat on a project Newly stores for you. Every chat in the web app is a Remote chat. On Mac, use a Remote chat. Otherwise the card shows "Publishing requires a saved Newly cloud project."
* **A plain `app.json` file.** Projects that configure the app with `app.config.js`, `app.config.ts` or any other `app.config` file can't publish. New Newly projects already use `app.json`.

<Tip>
  Never paste your Apple password, verification codes or keys into the chat. The card has its own secure sign-in, and the agent never sees what you enter there.
</Tip>

## Publish a build

<Steps>
  <Step title="Ask the agent">
    In your chat, send a message such as "publish to TestFlight". The agent opens the **Ship to TestFlight** card in the conversation.
  </Step>

  <Step title="Connect Apple">
    The first time you publish a project, the card asks you to sign in to App Store Connect and choose your team and app. See [Connect Apple and manage signing](/publish/connect-apple) for each option. Each project connects separately.
  </Step>

  <Step title="Check the version it will build">
    Once Apple is connected, the card shows your app's bundle ID and a line like "Build the saved revision 1a2b3c4d and upload it to Apple." That short code identifies the latest saved version of your project. If the card says "Finish and save the cloud project before publishing.", wait for the agent to finish its turn, which saves your project, then press **Refresh status**.
  </Step>

  <Step title="Start the upload">
    Press **Build & upload to TestFlight**.
  </Step>
</Steps>

## While it runs

The card shows where the release is:

1. "Preparing and submitting the release…"
2. "Waiting for a Mac builder…"
3. "Building, signing, and uploading…"

"You can close this tab. Publishing will continue." The release keeps going if you close the browser tab or the Mac app. Come back to the chat later to see the result.

Only one release can run for a project at a time. If you try to start another, you see "A release is already running for this project. Reopen its publishing card to follow it."

If the saved code changes after you opened the card, Newly asks you to look again: "The saved source changed. Refresh and review the new revision before publishing." Press **Refresh status** and check the new version before you start.

If you see "Submission was interrupted. Refresh status, then resume this release; do not start another upload.", press **Refresh status**, then **Resume release submission**.

## When the upload finishes

The card shows "✓ Uploaded to TestFlight". Apple may still be processing the build, so it can take a while before the build appears for testers. Press **Open App Store Connect** to go to your app's TestFlight page, add testers and follow Apple's processing.

What happens next, including testers and App Store review, is on [From TestFlight to the App Store](/publish/app-store-and-google-play).

## Version and build numbers

* **Build number:** Newly increases it automatically on each upload, so you don't have to change anything between releases.
* **Version:** the version your testers and users see comes from `expo.version` in your project's `app.json`. New projects start at `1.0.0`. To release a new version, ask the agent to change it. See [App name, icon, bundle ID and version](/publish/app-identity).

## If a release fails

The card shows the reason, with **View logs** and **Retry**.

* **View logs** shows the build and upload logs, with secrets removed.
* You can also ask the agent to read the logs and explain what went wrong. It can fix code problems in your project, but it won't revoke certificates or start a new upload for you. You press **Retry** yourself.

Common failures:

<AccordionGroup>
  <Accordion title="&#x22;Could not prepare the app source for publishing. Retry after checking the project source.&#x22;">
    Newly couldn't package your project for the build. Check that:

    * the project has a `package.json` and a plain `app.json` with an `expo` section at its top level, and no `app.config` file
    * the project has no more than 5,000 files and 100 MB in total, not counting `node_modules`, `.expo`, `.git` and `.env` files
    * no single file is larger than about 10 MB (large videos or datasets are the usual cause)
    * the project doesn't contain symbolic links

    Ask the agent to check these, then press **Retry**.
  </Accordion>

  <Accordion title="&#x22;Too many signing certificates&#x22; or &#x22;Signing certificate needs attention&#x22;">
    Your Apple team has hit its limit for distribution certificates, or Apple has a conflicting one. Use **Manage signing certificates** on the card. See [Signing certificates](/publish/connect-apple#signing-certificates).
  </Accordion>

  <Accordion title="The release fails after about an hour">
    A release build stops if it runs for more than 1 hour. Press **Retry**. If it keeps happening, contact support from the app. See [Getting help](/help/getting-help).
  </Accordion>

  <Accordion title="&#x22;Could not prepare or submit the release. Contact support with this session’s debug info.&#x22;">
    Newly couldn't finish setting up signing or sending the build. Contact support from the app and say which project and chat the release was in. See [Getting help](/help/getting-help).
  </Accordion>
</AccordionGroup>

## Credits

The cloud build and the upload to Apple don't draw down credits. The agent's chat turns do, including the message that opens the card and any turns where the agent reads logs or fixes your code. See [How credits work](/billing/how-credits-work).

## Android

Newly v2 doesn't produce Android builds you can install on a phone or upload to Google Play. See [From TestFlight to the App Store](/publish/app-store-and-google-play#google-play).

## Related

<CardGroup cols={2}>
  <Card title="Connect Apple and manage signing" icon="apple" href="/publish/connect-apple">
    Apple ID sign-in, API keys, and signing certificates.
  </Card>

  <Card title="From TestFlight to the App Store" icon="store" href="/publish/app-store-and-google-play">
    Testers, the store listing and App Store review.
  </Card>

  <Card title="Testing on a real phone" icon="mobile" href="/preview/test-on-a-phone">
    Install your app on your iPhone through TestFlight.
  </Card>

  <Card title="App name, icon, bundle ID and version" icon="id-card" href="/publish/app-identity">
    Change what users see and what Apple identifies.
  </Card>
</CardGroup>