Overview: Automating Beta Release Notes from Git History
When distributing pre-release builds through TestFlight, Apple provides a What to Test field (whatsNew). This text appears directly inside the TestFlight app on testers' devices and in their invitation notification emails, explaining what changed, which bugs were squashed, and where testers should focus their feedback.
Writing effective testing notes is frequently neglected or rushed during shipping, resulting in vague messages like "Bug fixes and performance improvements" that leave beta testers guessing.
With modern AI coding assistants (such as Cursor, Claude Code, Antigravity, or Windsurf), you can automate this workflow: your assistant inspects recent local Git commits, distills technical diffs into human-readable testing instructions, and prepares the update for TestFlight.
This guide explains the architectural boundaries between your local Git repository and Apple's servers, how to define the correct comparison range, Apple's character and localization rules, and how FlightDeck handles beta notes.
1. Architectural Boundaries: Local Git vs. FlightDeck MCP
To understand how AI creates TestFlight notes, you must recognize two distinct operating environments:
+-----------------------------------------------------------------------------------+
| ENVIRONMENT & CAPABILITY BOUNDARIES |
+-----------------------------------------------------------------------------------+
| |
| +----------------------------------+ +---------------------------------+ |
| | LOCAL IDE / ASSISTANT | | FLIGHTDECK MCP | |
| | (Cursor, Claude Code, etc.) | | (macOS Native Application) | |
| +----------------+-----------------+ +----------------+----------------+ |
| | | |
| v v |
| Inspects Local Worktree & Git Log Connects to Apple App Store Connect |
| - git status / git log - builds_list / build_get |
| - git diff [range] - build_beta_details_get |
| - Filters merge commits - Staged Change Sets & Governance |
| - Formulates natural language - Desktop Approval Center |
| | | |
| +-------------------+-------------------+ |
| | |
| v |
| App Store Connect Live Infrastructure |
| - /v1/betaBuildLocalizations (whatsNew) |
| - TestFlight Client App Delivery to Testers |
+-----------------------------------------------------------------------------------+
What Each Component Does
- Your AI Coding Assistant: Runs in your local development environment. It has direct access to your local filesystem, git repository, commit history, and release branches through its built-in terminal or shell tools. It reads code changes and synthesizes text.
- FlightDeck MCP: Operates as a local loopback server (
127.0.0.1:51122) connecting strictly to Apple's App Store Connect REST API. FlightDeck does not read your local.gitfolder, analyze branches, or inspect source code. - The Workflow Bridge: Your assistant queries FlightDeck to identify which build is currently live on TestFlight, inspects your local Git history between that build and
HEAD, generates user-facing "What to Test" copy, and stages the update for Apple.
2. Determining the True Git Comparison Range
A common failure in automated release notes is assuming that HEAD compared against the most recent Git tag reflects the changes in the new build. In real-world teams, Git tags and TestFlight uploads frequently diverge due to:
- Failed ingestion builds or CI rebuilds.
- Hotfixes cherry-picked across maintenance branches.
- Uploaded builds that were never distributed to testers.
Step 1: Verify the Preceding TestFlight Build
Before analyzing Git commits, instruct your assistant to inspect what build is actually active on TestFlight:
Using FlightDeck, check recent builds for [App Name] to identify which build testers currently have installed.
Identify the build number that testers currently have installed (for example, Version 1.2.0, Build 14).
Step 2: Establish the Git Commit Range
Instruct your assistant to locate the commit hash corresponding to that active build. If you tag your builds (e.g. build-14 or v1.2.0-14), compare against that specific tag:
# Explicit range between previous build tag and current commit
git log build-14..HEAD --oneline --no-merges
# Alternative: Commits since the last release tag
git log v1.2.0..HEAD --oneline --no-merges
Privacy Best Practice: Do not include raw Git commit hashes, internal Jira/Linear issue URLs, private repository paths, or developer nicknames in public TestFlight notes. Testers need clear behavioral instructions, not internal backlog metadata.
3. Structuring High-Quality 'What to Test' Notes
Apple's TestFlight client displays "What to Test" notes in a clean mobile card. High-quality notes follow a consistent four-part structure:
- Headline & Core Focus: One or two sentences summarizing the primary purpose of the build.
- New Features & Enhancements: Bullet points explaining visible UI or functional changes that testers can interact with.
- Bug Fixes: Clear descriptions of resolved crashes, UI glitches, or broken workflows.
- Targeted Testing Scenarios: Specific actions or edge cases you want testers to evaluate (e.g. "Try backgrounding the app during audio playback").
Example of Tester-Ready Copy:
Version 1.3.0 (Build 22) Focus: Offline Mode & Sync Reliability
What's New:
- Added offline queueing: Actions taken without internet connection now sync automatically when reconnected.
- Redesigned search bar with instant autocomplete.
Bug Fixes:
- Fixed a crash when opening large PDF attachments on iPad.
- Resolved an issue where push notifications failed to open the corresponding item.
Areas to Test:
1. Turn on Airplane Mode, create two new items, and disable Airplane Mode. Confirm both items sync cleanly.
2. Search for items containing non-English characters.
4. Apple Character Constraints & Localization Rules
Apple enforces specific technical constraints on TestFlight beta release notes:
| Constraint | Specification | Enforcement & Behavior |
|---|---|---|
| Character Limit | Up to 4,000 characters per localization. | Apple rejects notes exceeding 4,000 characters with HTTP 400 Bad Request. Recommended length is 300 to 1,000 characters for optimal mobile readability. |
| Localization Scope | Per-locale records (e.g. en-US, de-DE, ja). | Managed under Apple's /v1/betaBuildLocalizations resource. Each language receives its own whatsNew string. |
| Markdown / Rich Text | Plain text only. | The TestFlight app does not render HTML tags or Markdown formatting (bold, italics, links). Use plain bullets (- or •) and clean line breaks. |
| Prohibited Content | External payment references, vulgarity, or placeholder strings. | Violating App Review guidelines in beta notes (e.g. referencing unapproved payment mechanisms) can trigger Beta App Review rejection. Clear, informative notes ensure smooth review processing. |
5. End-to-End Prompt Workflow
Here is how to combine your assistant's local Git analysis with FlightDeck's verification capabilities in a single natural-language prompt:
Review our Git commit history since the last distributed TestFlight build of [App Name].
- Using FlightDeck, inspect our recent builds to identify the latest build number and its current processing state.
- Inspect the local Git log between the commit for the previous build and HEAD. Filter out merge commits and formatting tweaks.
- Draft concise, professional "What to Test" notes adhering to Apple's 4,000-character limit. Separate the draft into: - What's New (user-facing features) - Bug Fixes (resolved issues) - Focus Areas (specific steps for beta testers)
- Do not include raw commit hashes or private ticket IDs.
- Display the drafted notes for my review before proposing any App Store Connect changes.
6. How FlightDeck Handles 'What to Test' Updates
Inspecting Existing Beta Notes
To inspect existing What to Test notes already attached to a build on Apple's servers, FlightDeck's build_get tool retrieves the build record along with its linked betaBuildLocalizations.
Updating What to Test via FlightDeck MCP
FlightDeck intentionally focuses its high-level semantic tools on high-volume workflows (builds_list, build_get, build_add_to_beta_group). For granular localized beta notes, FlightDeck exposes two pathways:
- Staged Canonical Mutation (API Pathway): Your assistant can stage a
POSTorPATCHto Apple'sbetaBuildLocalizationsendpoint usingflightdeck_operation_stage(betaBuildLocalizations_createInstanceorbetaBuildLocalizations_updateInstance). This mutation is routed to the FlightDeck Desktop Approval Center for your explicit authorization.
- Web Portal Entry (Manual Pathway): Alternatively, developers frequently copy the AI-generated draft text directly into the App Store Connect portal: Navigate to App Store Connect $\rightarrow$ Apps $\rightarrow$ [Your App] $\rightarrow$ TestFlight. Click the newly uploaded build under iOS Builds. Under Test Information, paste the AI draft into the What to Test text area for your default locale. Click Save.
7. Read-Back Verification
Regardless of whether notes were updated via MCP staging or the web portal, your assistant can perform immediate read-back verification:
Using FlightDeck, inspect build [Build Number] and verify that the What to Test notes were successfully updated on Apple's servers. Display the recorded locale and text. The assistant verifies that Apple's response contains the updated whatsNew string, ensuring testers will see accurate instructions when they open TestFlight.
Summary of Best Practices
- Verify the Real Build Range: Always check recent builds in FlightDeck first to confirm which build testers currently have before running
git log. - Translate Dev Jargon: Instruct your assistant to turn technical commit messages (e.g.
refactor(db): migrate SQLite schema to v4) into tester-friendly descriptions (e.g.Improved local database performance and storage reliability). - Respect Plain Text Limits: Do not use markdown links, bolding, or raw HTML; the iOS TestFlight client does not render rich text formatting.
- Review Before Submitting: Read through the AI draft to ensure no unannounced features or internal notes leak into public beta distributions.