Overview: Transforming Technical Commits into Customer Release Notes
Every time you ship an update to the Apple App Store, Apple requires a localized "What's New" description (release notes) explaining what changed since the previous version. For developers and AI-assisted "vibe coders," compiling these notes often means manually sifting through weeks of Git commits, untangling cryptic messages like fix(auth): handle nil pointer dereference on token refresh or chore: update cocoapods lockfile, and rewriting them into polished, customer-facing prose.
By connecting your AI coding assistant (such as Cursor, Claude Code, Antigravity IDE, Windsurf, or Roo Code) to FlightDeck's Model Context Protocol (MCP) server, you can automate this entire pipeline safely. Your AI assistant inspects your local Git log between release tags, filters out internal refactors and technical jargon, synthesizes user-centric bullet points, and stages the updated release notes directly into App Store Connect for your human review in FlightDeck's native macOS Approval Center.
┌────────────────────────────────────────────────────────────────────────┐
│ LOCAL REPOSITORY (IDE / AI ASSISTANT) │
│ │
│ Git History ──► [ git log v1.0.0..HEAD ] ──► Raw Commits │
│ │ │
│ ▼ │
│ AI Filtering & Synthesis ──► Customer-Friendly "What's New" Draft │
└─────────────────────────────────────┬──────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────────────────┐
│ FLIGHTDECK MCP STAGING & GOVERNANCE │
│ │
│ AI Assistant Calls: [ app_store_version_localization_update ] │
│ │ │
│ ▼ │
│ Desktop Approval Center ──► Human Inspects Diff & Clicks [Approve] │
│ │ │
│ ▼ │
│ Direct Apple API ─────────► App Store Connect Draft Updated (TLS) │
└────────────────────────────────────────────────────────────────────────┘
Separation of Concerns: FlightDeck is a native macOS management client for the App Store Connect REST API. FlightDeck itself does not read your local Git repository, execute shell commands, or parse Git commit logs. Instead, your local AI assistant—which has access to your local workspace—runs git log, analyzes the commit history, and passes the polished release notes to FlightDeck across MCP. FlightDeck then handles payload validation, human-in-the-loop approval, and direct Apple cloud transmission.
Quick Answer: How to Automate Release Notes via AI
To generate customer-ready release notes from your Git commit history and push them to App Store Connect:
- Open your AI coding assistant in your project repository.
- Ask your assistant to compare commits between your last release tag and
HEAD, group user-facing improvements, and propose an update to App Store Connect. - Review the assistant's drafted release notes in your chat conversation.
- When FlightDeck creates an immutable Staged Change Set, switch to the FlightDeck Desktop Approval Center to inspect the diff and character counts.
- Click Approve. FlightDeck commits the release notes directly to Apple's API and returns an authoritative confirmation.
Copyable Prompts for Your AI Coding Assistant
Primary Release Notes Automation Prompt
Use this prompt to instruct your AI assistant to read your local Git history, draft user-facing release notes, and prepare the App Store Connect update:
Inspect the Git commits in this repository between our previous release tag and current HEAD (or the last 20 commits if no tags exist, e.g., `git log $(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~20)..HEAD --oneline`).
Please:
1. Filter out internal developer changes (refactors, CI/CD scripts, dependency bumps, test suites, and chore commits).
2. Even if commits do not use conventional commit prefixes (feat:, fix:), analyze the commit descriptions for semantic intent to identify user-visible bug fixes, new features, and performance enhancements.
3. Strictly sanitize all output: strip internal issue tracker keys (e.g., JIRA-123, #456), private staging URLs, employee names, or internal codenames.
4. Synthesize these improvements into concise, polished, customer-friendly bullet points suitable for the App Store "What's New" section (maximum 4,000 characters, plain text, no Markdown).
5. Query App Store Connect via FlightDeck to find our current editable draft version and inspect its English localization.
6. Show me your drafted release notes first. Once I confirm, propose the update to our draft version's What's New field using FlightDeck.
Multilingual Localization Expansion Prompt
Once you have approved the primary release notes, expand them across all target storefront languages:
Our English release notes for the upcoming version are approved. Please:
1. Query FlightDeck for all configured version localizations on our draft version.
2. Translate our approved English release notes into each configured language (e.g., Spanish, French, German, Japanese, Simplified Chinese), maintaining a natural, native tone and preserving bullet formatting.
3. Present a table showing each locale code and the corresponding translated text with character counts.
4. Stage the updates in FlightDeck so I can review each language in the Desktop Approval Center before committing to Apple.
Apple Guidelines and Formatting Invariants
Apple enforces strict constraints on the "What's New" release notes field. Ensure your AI assistant adheres to these rules:
| Rule / Constraint | Specification | Failure Mode / Apple Rejection |
|---|---|---|
| Character Limit | Exactly 4,000 characters maximum per locale. | HTTP 400 validation error from App Store Connect API if exceeded. |
| Formatting | Plain text only. No HTML tags, Markdown bolding (**), or italics. |
Markdown asterisks or HTML tags render literally on customer devices. |
| Version Availability | Available only on version updates (Version 1.0.1+). Version 1.0 has no What's New field. | API error if attempting to write whatsNew on a version 1.0 draft. |
| Prohibited Content | No pricing promises ("Now only \$4.99!"), mentions of other platforms ("Also on Android"), or references to beta testing. | Guideline 2.3 (Accurate Metadata) or Guideline 2.2 (Beta References) rejection. |
| Vague Placeholders | Generic copy like "Bug fixes and performance improvements" is technically accepted by the API, but Apple Reviewers may challenge it if significant changes were detected. | Review delay or requests for clarification under Guideline 2.3. |
Bullet Formatting in Plain Text: Because the App Store does not parse Markdown, use standard Unicode bullet characters (• or - ) followed by a space. Do not use numbered lists unless the sequence matters, as translation line lengths vary significantly between languages.
Step-by-Step Implementation Workflow
sequenceDiagram
autonumber
actor Dev as Developer
participant AI as AI Coding Assistant (IDE)
participant Git as Local Git Worktree
participant FD as FlightDeck Desktop (MCP)
participant Apple as Apple App Store Connect
Dev->>AI: "Draft What's New from Git commits"
AI->>Git: git log [last_tag]..HEAD
Git-->>AI: Raw commit history
AI->>FD: app_store_versions_list(appId)
FD->>Apple: GET /v1/apps/{id}/appStoreVersions
Apple-->>FD: Active draft version details
FD-->>AI: Draft versionId and state
AI->>FD: app_store_version_localizations_list(versionId)
FD->>Apple: GET /v1/appStoreVersions/{id}/appStoreVersionLocalizations
Apple-->>FD: Existing localizations
FD-->>AI: localizationId (en-US, etc.)
AI->>Dev: Presents synthesized bullet points
Dev->>AI: "Looks good, stage the update"
AI->>FD: app_store_version_localization_update(...)
Note over FD: FlightDeck stages proposal<br/>Calculates SHA-256 change set
FD-->>AI: STAGED (Requires Desktop Approval)
AI-->>Dev: "Proposal staged in FlightDeck Approval Center"
Dev->>FD: Inspects diff & clicks [Approve]
FD->>Apple: PATCH /v1/appStoreVersionLocalizations/{id}
Apple-->>FD: HTTP 200 OK (Persisted)
FD-->>Dev: Mutation committed successfully
Step 1: Local Git Commit Extraction and Filtering
Your AI assistant runs Git commands locally in your workspace to isolate relevant commits:
# Locate the most recent tag (falling back to initial commit if no tags exist)
PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
# Extract commits since the tag
git log ${PREV_TAG}..HEAD --pretty=format:"%s (%an)" --no-merges
The AI assistant categorizes the commit log and extracts user-facing value:
feat:-> Mapped to customer-facing feature announcements.fix:-> Mapped to user-visible resolved issues (e.g., "Resolved an issue where audio playback paused unexpectedly in the background").perf:-> Mapped to responsiveness and speed enhancements.chore:,refactor:,test:,ci:-> Strictly filtered out of customer release notes.
Handling Non-Conventional Commits & Sanitization: If your repository does not follow conventional commit standards, the assistant inspects the plain-English commit descriptions for semantic intent. In all cases, the assistant explicitly strips sensitive internal metadata—such as ticket numbers (JIRA-1024, #582), internal server domains, developer handles, or private API keys—ensuring that only polished, customer-safe prose reaches App Store Connect.
Step 2: Querying App Store Connect for the Active Draft
Before modifying metadata, the AI assistant inspects current App Store Connect state:
- Calls
app_store_versions_listto locate the version inPREPARE_FOR_SUBMISSIONorDEVELOPER_REJECTEDstate. - Calls
app_store_version_localizations_listusing the draftversionIdto retrieve thelocalizationIdfor each language.
Step 3: Staging the Update via FlightDeck
With the localizationId identified and customer-facing bullets drafted, the assistant invokes FlightDeck MCP:
{
"localizationId": "loc_en_us_987654321",
"whatsNew": "• Added offline caching for saved articles and media.\n• Improved search responsiveness when browsing large archives.\n• Resolved an issue where push notification badges failed to clear upon app launch.\n• General stability improvements across iOS 18 devices."
}
Under FlightDeck's default security configuration (AI Approval: ON), FlightDeck intercepts the mutation, verifies that the text length is within the 4,000-character ceiling, and creates a cryptographic Change Set in the Desktop Approval Center.
Step 4: Inspecting and Approving in FlightDeck Desktop
Switch to the FlightDeck desktop application. The Approval Center surfaces a confirmation card detailing:
- Operation: Update App Store Version Localization
- Target Locale:
en-US(English (U.S.)) - Version:
1.2.0 - Field Modified:
whatsNew - Character Count:
274 / 4,000 characters - Side-by-Side Diff: Displays the previous release notes versus the proposed new bullet points.
Click Approve. FlightDeck immediately delivers the verified payload directly to Apple's API over TLS.
Authoritative Readback Verification
To verify that Apple has persisted the updated release notes without truncation or encoding defects, run this verification prompt with your assistant:
Please perform an authoritative readback of the "What's New" text for our draft version using FlightDeck. Confirm that the persisted text matches our approved release notes word-for-word and that the character count is well within Apple's 4,000-character limit.
The assistant calls app_store_version_localization_get(localizationId: "...") and displays the live Apple record to confirm success.
Troubleshooting Common Issues
1. "What's New is not allowed for the initial app version"
- Cause: You are preparing Version 1.0.0 of your app. Apple does not display or allow a What's New section on the initial release, because the entire app is new.
- Fix: For Version 1.0, focus all descriptive copy into the primary
descriptionfield. Only updates (Version 1.0.1 and later) supportwhatsNew.
2. "The version is not in an editable state"
- Cause: Calling
app_store_version_localization_updateon a version that is currentlyREADY_FOR_SALE,WAITING_FOR_REVIEW, orIN_REVIEW. - Fix: If the version is live, you must create a new draft version first (e.g., via
app_store_version_create). If the version is in review, you must wait for review completion or cancel the submission before release notes can be edited.
3. Markdown Formatting Rendering as Literal Characters
- Cause: Submitting release notes containing Markdown formatting like
New FeaturesorLearn More. - Fix: The iOS App Store app does not render Markdown. Strip all asterisks, brackets, and raw URLs from release notes. Use clean Unicode bullets (
•) and standard capitalized section headings.
Security and Governance Safeguards
- Keychain Protection: Private
.p8API keys and credentials remain in your Mac's Keychain (kSecClassGenericPassword). Tokens are signed locally with short 15-minute expirations. - Direct Apple Cloud Connection: All API requests travel directly between your Mac and Apple (
https://api.appstoreconnect.apple.com) without routing through a FlightDeck relay server. - Fail-Closed Staging: If an assistant drafts release notes containing invalid characters, missing localization IDs, or text exceeding 4,000 characters, FlightDeck rejects the payload locally before contacting Apple.
- Audit Trails: Every approved and committed release notes update is recorded in FlightDeck's immutable operation log with cryptographic SHA-256 payload hashes.
Official Documentation & Related Guides
Official Apple Documentation
- App Store Connect API: Update an App Store Version Localization
- App Store Review Guidelines: Section 2.3 Accurate Metadata
- Apple Developer: What's New in Your App