Skip to main content
First-time vibe coding to App Store Level: Intermediate 12 min read

Shipping Version 1.1: Managing App Store Updates and Changelogs via AI

The complete step-by-step developer guide to shipping an app update: creating draft versions, attaching builds, updating localized What's New changelogs, and submitting for App Review via FlightDeck MCP.

Published: 2026-11-02 • Last Updated: 2026-11-02 • Author: Kip Lawrence
Key MCP Tools: app_store_versions_listapp_store_version_createrelease_build_candidatesrelease_build_selectapp_store_version_localization_updaterelease_readiness_checkreview_submission_create_draftreview_submission_submit

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:

  1. You Cannot Modify a Live Version: Once a version reaches READY_FOR_SALE, its binary, description, and keywords are permanently frozen.
  2. 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.
  3. 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:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   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 ]            │
└────────────────────────────────────────────────────────────────────────┘
Important

Separation of Pipeline Responsibilities:

  • Local Compilation (Xcode / CLI): Building your project into an .ipa or .pkg binary is performed on your Mac using xcodebuild, 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:

  1. Compile and upload your new build (with an incremented build number, e.g., CFBundleVersion 2) to App Store Connect.
  2. Instruct your AI assistant to check live status and create a new version draft (1.1.0) specifying your release type (AFTER_APPROVAL or MANUAL).
  3. Approve the version draft creation in FlightDeck Desktop.
  4. Have the assistant link your uploaded build to the draft using release_build_select.
  5. Generate customer-facing release notes from your Git history and stage them via app_store_version_localization_update.
  6. 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

MARKDOWN
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

MARKDOWN
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

MARKDOWN
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...
Warning

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

MERMAID
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:

  1. Call release_build_candidates(versionId: "...") to list builds that match the version platform and have passed Apple's ingestion scanning.
  2. Stage release_build_select(versionId: "...", buildId: "...").
  3. 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:

MARKDOWN
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_update to 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 PROCESSING cannot be attached to a version draft. Wait 5–15 minutes, query release_build_candidates, and proceed once the status transitions to VALID.

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 Apple Documentation

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