Skip to main content
TestFlight and beta distribution Level: Developer 10 min read

Selecting a TestFlight Build for an App Store Release Version

How to associate and link a validated TestFlight build to your App Store release version using natural-language prompts with your AI coding assistant and FlightDeck.

Published: 2026-10-31 • Last Updated: 2026-11-01 • Author: Kip Lawrence
Key MCP Tools: apps_listapp_store_versions_listrelease_build_candidatesrelease_build_select

Direct Answer: Linking Your Build to a Release Version

Having a build circulating in TestFlight does not automatically attach it to your upcoming App Store release. In Apple's data model, an App Store Version (which holds your version string, screenshots, and localized descriptions) and an Uploaded Build (the binary archive compiled on your Mac) are separate entities.

Before you can submit your application to Apple App Review, you must explicitly link an eligible, processed build to your editable version draft.

With FlightDeck, you do not need to navigate the App Store Connect web portal or look up internal build identifiers. You simply ask your AI coding assistant to find your eligible builds and stage the selection. FlightDeck displays a confirmation card in the native Desktop Approval Center. You review the proposed change, click Approve, and your release draft is linked and ready for pre-submission checks.


What You Need

Before linking a build, ensure:

  1. FlightDeck for Mac: Running and connected to your AI assistant (see our Cursor Setup Guide or Claude Code Guide).
  2. Editable Version Draft: An App Store version currently in PREPARE_FOR_SUBMISSION (such as version 1.0.0).
  3. Processed Build: At least one uploaded binary that has finished processing on Apple's servers (VALID state).

Conceptual Model: Versions vs. Builds in App Store Connect

Understanding Apple's relationship model prevents common submission errors:

TEXT
[App Store Version Container (e.g. 1.0.0)]
  ├── Localized Descriptions, Keywords, and URLs
  ├── Screenshots & App Previews
  ├── Review Notes & Demo Account Credentials
  └── Build Relationship: (Selects one specific build binary)
                                ▲
                                │  Associated via FlightDeck
                                │
[Uploaded Builds Collection in TestFlight]
  ├── Build 1.0.0 (Build 41) [VALID • Superseded]
  ├── Build 1.0.0 (Build 42) [VALID • Selected Release Candidate]
  └── Build 1.0.0 (Build 43) [PROCESSING • Not yet eligible]

Three Rules to Keep in Mind:

  1. Version Must Be Editable: A build can only be attached or swapped while your version draft is in an editable state (PREPARE_FOR_SUBMISSION, DEVELOPER_REJECTED, or REJECTED). Once submitted to review, the build relationship is locked.
  2. Build Must Be Valid: Apple's ingestion servers must have completed processing the binary. Builds still in PROCESSING cannot be attached.
  3. Selecting Is Not Submitting: Linking a build attaches the binary to your storefront version container. It does not send the application to Apple App Review. You retain full control to audit metadata and run readiness checks before submitting.

Step-by-Step Solution: Linking Your Build with AI

Step 1: Discover Eligible Candidate Builds (Prompt)

Instruct your assistant to inspect your app and report which builds are processed and ready for release:

Copy and paste this prompt into Cursor, Claude Code, Antigravity, or Windsurf:

TEXT
Check App Store Connect for [Your App Name]. Find our active release version draft, and show me all eligible candidate builds that Apple has processed and are ready to be attached.

What Your Assistant Does:

  1. It queries App Store Connect to identify your active version draft (e.g., 1.0.0 in PREPARE_FOR_SUBMISSION).
  2. It evaluates all uploaded builds, filtering for platform compatibility (iOS), valid processing state, and cleared export compliance.
  3. It presents the candidate build numbers, upload dates, and indicates which build is currently attached (if any).

Step 2: Propose and Stage the Build Selection (Prompt)

Once you identify the build number you wish to release (for example, build 42), instruct your assistant to stage the change:

TEXT
Attach build [Build Number, e.g., 42] to our version [Version String, e.g., 1.0.0] release draft for [Your App Name]. Prepare the proposal for my approval in FlightDeck.

What Your Assistant Does:

  1. It verifies that build 42 is eligible and matches the version container's target platform.
  2. It stages a mutation proposal without modifying your live account yet.
  3. A native proposal card appears in the FlightDeck Desktop Approval Center on your Mac.

Step 3: Authorize in the FlightDeck Desktop Approval Center

Because linking a build determines which binary code Apple will review and publish to customers, FlightDeck requires human confirmation:

Illustrative representation of the FlightDeck Approval Center sheet:

TEXT
┌─────────────────────────────────────────────────────────────────────────────┐
│                 FlightDeck Desktop Approval Center                          │
├─────────────────────────────────────────────────────────────────────────────┤
│ Operation:    Associate Build with App Store Version Draft                  │
│ Application:  FocusFlow (ID: 6812899314)                                    │
│ Version:      1.0.0 (Status: PREPARE_FOR_SUBMISSION)                       │
│ Selected:     Build 42 (Uploaded: Oct 31, 2026 • State: VALID)              │
│ Replacing:    None (Initial build assignment)                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                          [ Reject ]    [ Approve ]                          │
└─────────────────────────────────────────────────────────────────────────────┘
  1. Inspect the card to ensure the target version and build number match your release candidate.
  2. Click Approve.
  3. FlightDeck executes the relationship update directly against Apple's API.

Verify Success: Confirming Build Association

Confirm that the build is securely attached by asking your assistant:

TEXT
Verify that build [Build Number] is now successfully linked to version [Version String] on [Your App Name] in App Store Connect. Also check if the release draft is ready for submission.

What Your Assistant Returns:

  • Confirms that the version container now points to the chosen build.
  • Verifies that buildAttached reports true.
  • Informs you whether any other required release assets (such as screenshots or privacy URLs) are missing before you submit for review.

Replacing an Attached Build

If you discover a bug after linking a build, you do not need to delete your version draft or re-enter metadata:

  1. Bump your build number (e.g., from 42 to 43), compile, and upload the new .ipa.
  2. Wait for Apple to finish processing.
  3. Paste this prompt: ``text Replace the attached build on version [1.0.0] of [Your App Name] with our new build [43]. Stage the change for my approval in FlightDeck. ``
  4. Click Approve in the FlightDeck Desktop Approval Center. Apple updates the binary association cleanly without affecting your saved descriptions, keywords, or screenshots.

Troubleshooting Common Issues

1. Build Not Listed as an Eligible Candidate

  • Symptom: A build you uploaded recently does not appear in candidate suggestions.
  • Cause 1 (Processing Delay): Apple's servers are still processing the binary. Ask your assistant: ``text Check if the latest build for [Your App Name] has finished processing yet. ``
  • Cause 2 (Missing Compliance): The build is flagged for missing export compliance. Add <key>ITSAppUsesNonExemptEncryption</key><false/> to Info.plist or clear the compliance prompt in App Store Connect.

2. Version State Is Not Editable (HTTP 409 Conflict)

  • Symptom: Your assistant reports that the version cannot accept build updates.
  • Cause: The App Store version is currently WAITING_FOR_REVIEW, IN_REVIEW, or already READY_FOR_SALE.
  • Resolution: If the app is in review, you must cancel the review submission before you can swap the build. If the version is already published, you must create a new version draft (e.g., 1.0.1).

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store