Overview: The App Store Update Lifecycle
Shipping Version 1.0 of your iOS or macOS application is a major milestone—but keeping users engaged requires continuous updates, bug fixes, and new features. For developers building with AI coding assistants (like Cursor, Claude Code, Antigravity IDE, Windsurf, or Roo Code), transitioning from "Version 1.0 is live" to "Shipping Version 1.1" introduces a new set of App Store Connect rules:
- You Cannot Modify a Live Version: Once a version reaches
READY_FOR_SALE, its binary, description, and keywords are permanently frozen. - Updates Require a Dedicated Version Draft: You must explicitly create a new App Store Version draft (e.g., Version
1.1.0), attach a newly compiled binary build, and draft a customer-facing "What's New" release note. - App Review Evaluates the Delta: Apple reviews every update. While minor point releases typically pass review faster than initial launches, reviewers check that your changelog accurately reflects changes and does not introduce regression bugs or policy violations.
FlightDeck automates this entire lifecycle through conversational AI prompts while preserving strict human-in-the-loop governance:
┌────────────────────────────────────────────────────────────────────────┐
│ THE 6-STAGE APP STORE UPDATE PIPELINE │
│ │
│ 1. Inspect Live State ──► Verify Version 1.0 is READY_FOR_SALE │
│ 2. Create Version Draft ──► [ app_store_version_create ] ("1.1.0") │
│ 3. Attach Processed Build─► [ release_build_select ] (Build 2) │
│ 4. Stage What's New ──► [ app_store_version_localization_update ] │
│ 5. Pre-Flight Readiness ──► [ release_readiness_check ] (0 Blockers) │
│ 6. Submit for Review ──► [ review_submission_submit ] │
└────────────────────────────────────────────────────────────────────────┘
Separation of Pipeline Responsibilities:
- Local Compilation (Xcode / CLI): Building your project into an
.ipaor.pkgbinary is performed on your Mac usingxcodebuild, Flutter, React Native, or Fastlane. - FlightDeck MCP: Manages App Store Connect version drafts, build selection, localized release notes, pre-submission readiness audits, and review submissions.
- FlightDeck Desktop Approval Center: Requires you to physically click Approve on confirmation cards before any draft is created, build linked, or review submitted.
Quick Answer: The 6-Step Command to Ship Version 1.1
To ship an update to an existing live application:
- Compile and upload your new build (with an incremented build number, e.g.,
CFBundleVersion2) to App Store Connect. - Instruct your AI assistant to check live status and create a new version draft (
1.1.0) specifying your release type (AFTER_APPROVALorMANUAL). - Approve the version draft creation in FlightDeck Desktop.
- Have the assistant link your uploaded build to the draft using
release_build_select. - Generate customer-facing release notes from your Git history and stage them via
app_store_version_localization_update. - Run
release_readiness_check, review the final Approval Center card, and submit for App Review.
Copyable Prompts for Your AI Coding Assistant
Stage 1: Create Version Draft & Discover Builds
Our app "Quest Companion" version 1.0 is currently live on the App Store, and I have just uploaded a new build for Version 1.1.0:
1. Query App Store Connect via FlightDeck to confirm our live version status and check if a draft already exists.
2. If no draft exists, propose creating a new version draft for "1.1.0" on the iOS platform with automatic release after approval.
3. Discover available processed builds matching version 1.1.0 using FlightDeck.
4. Propose attaching the latest valid build to our new draft version.
5. Pause for my review in the FlightDeck Desktop Approval Center.
Stage 2: Stage What's New Release Notes
Now that version 1.1.0 is created and build 2 is attached:
1. Review our recent Git commits since the v1.0.0 tag to identify user-facing bug fixes and improvements.
2. Draft a concise, customer-friendly "What's New" release note (plain text, Unicode bullets, under 4,000 characters).
3. Query FlightDeck to find the English (US) localization on our draft version.
4. Stage the update to our draft version's What's New field using FlightDeck.
Stage 3: Pre-Flight Readiness Audit & Review Submission
We are ready to submit Version 1.1.0 for App Review:
1. Audit our 1.1.0 draft version for submission readiness using FlightDeck.
2. Verify that all blockers, warnings, and missing metadata fields are completely resolved.
3. If the readiness check passes, prepare the App Review submission and stage it for my approval in the FlightDeck Desktop Approval Center.
4. Show me the final submission summary before I approve the card in FlightDeck Desktop.
Versioning Rules: Version String vs. Build Number
Apple enforces two distinct versioning identifiers for every update:
| Identifier | Xcode Setting / Plist Key | App Store Connect Rule | Example Progression |
|---|---|---|---|
| Version String | CFBundleShortVersionString |
Public-facing marketing version. Must follow Semantic Versioning (X.Y.Z). Increment when releasing new features or fixes. |
1.0.0 -> 1.0.1 -> 1.1.0 -> 2.0.0 |
| Build Number | CFBundleVersion |
Internal machine integer or point sequence. Must be strictly monotonically increasing within each version train. | Build 1, Build 2, Build 3... |
Duplicate Build Number Rejection: If you attempt to upload a new binary for Version 1.1.0 using the same build number as a previously uploaded binary (e.g., both marked CFBundleVersion: 1), Apple's upload ingestion service rejects the upload with ITMS-90189: Redundant Binary Upload. Always increment your build number before archiving.
Detailed Step-by-Step Walkthrough
sequenceDiagram
autonumber
actor Dev as Developer
participant AI as AI Assistant (IDE)
participant FD as FlightDeck Desktop (MCP)
participant Apple as App Store Connect
Note over Dev,Apple: Phase 1: Create Version Draft
Dev->>AI: "Create draft version 1.1.0"
AI->>FD: app_store_versions_list(appId)
FD->>Apple: GET /v1/apps/{id}/appStoreVersions
Apple-->>FD: Version 1.0 (READY_FOR_SALE)
FD-->>AI: Confirms 1.0 is live, zero drafts exist
AI->>FD: app_store_version_create(versionString: "1.1.0", platform: "IOS")
Note over FD: Staged in Desktop Approval Center
FD-->>AI: STAGED (Awaiting Approval)
AI-->>Dev: "Approval card ready: Create Version 1.1.0"
Dev->>FD: Clicks [Approve]
FD->>Apple: POST /v1/appStoreVersions
Apple-->>FD: HTTP 201 Created (versionId: "ver_110")
Note over Dev,Apple: Phase 2: Attach Build & Update Notes
Dev->>AI: "Attach latest build and set What's New"
AI->>FD: release_build_candidates(versionId: "ver_110")
FD->>Apple: GET /v1/builds?filter[app]=...
Apple-->>FD: Candidate Build (ID: "bld_2", status: "VALID")
FD-->>AI: Eligible build discovered
AI->>FD: release_build_select(versionId: "ver_110", buildId: "bld_2")
Note over FD: Staged in Desktop Approval Center
Dev->>FD: Clicks [Approve]
FD->>Apple: PATCH /v1/appStoreVersions/{id}/relationships/build
Apple-->>FD: HTTP 204 No Content (Build Attached)
AI->>FD: app_store_version_localization_update(...)
Dev->>FD: Clicks [Approve]
FD->>Apple: PATCH /v1/appStoreVersionLocalizations/{id}
Note over Dev,Apple: Phase 3: Submit for App Review
AI->>FD: release_readiness_check(versionId: "ver_110")
FD->>Apple: Preflight readiness validation
Apple-->>FD: Status: READY_FOR_SUBMISSION (0 Blockers)
AI->>FD: review_submission_submit(versionId: "ver_110")
Note over FD: Final Confirmation Card
Dev->>FD: Clicks [Approve]
FD->>Apple: POST /v1/reviewSubmissions
Apple-->>FD: HTTP 201 Created (Status: WAITING_FOR_REVIEW)
FD-->>Dev: Version 1.1.0 successfully submitted!
Step 1: Draft Creation and Release Type Selection
When creating a version draft via app_store_version_create, you choose how the update will release once approved:
AFTER_APPROVAL: Automatically releases to the App Store immediately upon Apple approval.MANUAL: Holds the approved version until you manually click Release This Version in FlightDeck or App Store Connect.SCHEDULED: Automatically releases at a specific future ISO-8601 date and time.
Step 2: Build Discovery and Linking
Before submitting, a binary build with status VALID must be bound to the draft version:
- Call
release_build_candidates(versionId: "...")to list builds that match the version platform and have passed Apple's ingestion scanning. - Stage
release_build_select(versionId: "...", buildId: "..."). - In FlightDeck Desktop, verify the build number, commit hash, and upload timestamp before approving.
Step 3: Localized "What's New" Changelog
Every configured language must have release notes. Your AI assistant translates your primary notes and stages updates using app_store_version_localization_update.
Step 4: Submission and Pre-Flight Validation
FlightDeck's release_readiness_check verifies that:
- A valid build is attached.
- What's New is populated for all active locales.
- Support URL and Marketing URLs are valid HTTPS.
- Export compliance attestation is completed.
- Privacy nutrition labels are current.
Once zero blockers remain, calling review_submission_submit creates the App Review draft, attaches the version, and places the update into Apple's review queue.
Authoritative Readback Verification
To verify that Version 1.1.0 is officially queued for review:
Query App Store Connect via FlightDeck to inspect our version 1.1.0 status and review submissions. Confirm that the state is "WAITING_FOR_REVIEW" and output the estimated review status.
FlightDeck calls app_store_versions_list and review_submissions_list, confirming that the update is in Apple's hands.
Troubleshooting Update Issues
1. "A version draft already exists for this app"
- Cause: You previously started a draft version in App Store Connect that was never submitted.
- Fix: Have your AI assistant call
app_store_versions_list. If an unsubmitted draft exists, reuse that version ID rather than creating a duplicate.
2. "Missing 'What's New' release notes"
- Cause: Attempting to submit a version update without release notes.
- Fix: While initial Version 1.0 launches do not have a What's New field, every version update (1.0.1+) requires What's New. Use
app_store_version_localization_updateto add release notes.
3. "Build is still in PROCESSING state"
- Cause: You uploaded the binary recently and Apple's backend has not finished ingestion scanning.
- Fix: Builds in
PROCESSINGcannot be attached to a version draft. Wait 5–15 minutes, queryrelease_build_candidates, and proceed once the status transitions toVALID.
Security & Verification Safeguards
- Multi-Stage Approval: Draft creation, build attachment, metadata updates, and review submission are isolated into separate Approval Center change sets.
- No Accidental Submissions: An AI assistant cannot submit your app to Apple without an explicit, physical click on the Desktop Approval Center card.
- Zero Intermediaries: Build metadata, changelogs, and review requests stream directly between your Mac and Apple's secure servers over TLS 1.3.
Official Documentation & Related Guides
Official Apple Documentation
- App Store Connect Help: Create a New Version
- App Store Review Guidelines: Submitting Updates
- App Store Connect API: Create an App Store Version