iOS version and build numbers: avoid TestFlight and review confusion
How to increment CFBundleShortVersionString and CFBundleVersion; numbering after rejections and hotfixes. Telegram @hagee66.
Site hub (click through)
Open this guide · Guide library · Apple listing · Google Play listing · Both stores
Telegram @hagee66 · goee.cc
In App Store Connect, version and build do different jobs: the marketing version users see, and the binary identifier for every upload. Mixing them, going backward, or reusing an old build leads to TestFlight testers installing the wrong IPA, review builds you cannot select, and “we fixed it but the store still shows the old build.” This guide gives iOS and listing teams copyable increment rules and ties to TestFlight and review tips and What’s New writing. Apple’s format and limits follow official current documentation. Correct numbering does not guarantee approval. Goee goee.cc · Telegram @hagee66.
Problems this guide addresses
- Marketing string changed but
CFBundleVersiondid not—ASC rejects upload or TestFlight does not show the new build. - After a small rejection fix you bumped marketing; users assume a major release and What’s New / promo text no longer match.
- Dozens of builds under one marketing version; notes say “see build 37” while customers only see 1.2.0.
- iOS build and Android
versionCodeland on one release note line—support cannot tell what users installed. - Hotfix under pressure: should marketing version move?
Who should read
- iOS engineers: Info.plist / Xcode settings, CI auto-bump.
- Listing ops: create versions in ASC, pick builds, fill What’s New.
- Product / ops: version story for users; align with phased release when applicable.
- Support: map user reports to builds that include a fix.
Materials checklist: App Store materials.
Core practice
Two fields
| Field | Info.plist key | Typical use |
|---|---|---|
| Marketing version | CFBundleShortVersionString | User-visible, e.g. 1.3.0 |
| Build | CFBundleVersion | Unique increment per upload, e.g. 87 |
Rules:
- Every ASC upload must have
CFBundleVersiongreater than any prior upload for that app (string comparison per Apple docs; plain integers are safest in practice). - Change
CFBundleShortVersionStringwhen product ships a new marketing story; bugfix-only releases may keep marketing and only bump build. - TestFlight and App Store review share builds; testers’ version/build pairs should map to your release log.
Recommended strategies (put in README)
Strategy A: linear build (good for small teams)
- Marketing: semver MAJOR.MINOR.PATCH per product decision.
- Build: global monotonic integer (CI +1); never reset.
Strategy B: marketing-bound build (use with care)
- e.g. 1.3.0 (10300). Readable but fragile if numbers skip—generate via script.
Never: roll back build, reuse an uploaded build number, or edit plist locally without archiving.
Scenario table
| Scenario | Marketing | Build | What’s New |
|---|---|---|---|
| Regular iteration | May bump minor | +1 | User-visible features |
| Rejection fix (not a public rewrite) | Usually unchanged | +1 | Avoid “rebuilt entire app”; see rejection guide |
| External TestFlight | Match planned review or slightly ahead | +1 per upload | TF notes for internal testers |
| Hotfix on live | PATCH +1 or unchanged (product) | +1 | Honest fix list |
| Parallel branches | One rule on main | No colliding builds on branches | Release owner bumps before merge |
For dual-store release days, put iOS build and Android versionCode on separate lines in the release note—not one “version 42.”
ASC order (conceptual)
- Xcode Archive → Upload (build is inside the IPA).
- Wait for ASC processing → testers see build / you can attach to version.
- Create or select App Store Version (marketing) → pick Build.
- Fill What’s New and review notes.
UI labels change—follow App Store Connect as it is today.
CI vs humans
- CI:
agvtoolor script bump; tagbuild-87. - Human: release owner approves marketing changes.
- Forbidden: several people bump locally without commit—repo plist disagrees with uploaded binary.
TestFlight and phased release
- External testing still needs unique builds; log feedback as “build + date.”
- Phased release is rollout percentage for an approved version—it does not replace build discipline. See phased release strategy.
Copyable templates
iOS release log
[iOS release log]
Product:
Marketing version:
Build (CFBundleVersion):
Delta from last uploaded build: +N
User-visible change (one line):
Branch / tag:
Uploaded to ASC:
Processing complete:
TestFlight: internal / external
App Store submit: Y / N
What’s New owner:
Review notes updated: Y / N
Known not included:
Rejection rebuild numbering
[Rejection rebuild]
Rejected on:
Original marketing / build:
New build (must increase):
Marketing changed: N (default) / Y (why)
User-visible What’s New: none / yes (text)
Added review note paragraph (summary):
Dual-store alignment
Release date:
iOS marketing / build:
Android versionName / versionCode:
Same external “version story”: Y / N
Support script when users ask version:
Common mistakes
- Changed display version in Xcode, forgot plist. Upload still has old build.
- Marketing moves every day with build. Confuses users and store history.
- After rejection, marketing jumps 1.2 → 2.0. No product reason.
- Different marketing stories for TestFlight vs review. Notes do not match.
- Extensions share bundle but builds drift. Watch / extension rule violations.
- Reuse rejected build number on re-upload. Not allowed.
- What’s New says “all-new version” but marketing unchanged. Metadata risk—see rejection fix.
Q&A
Can build strings contain dots?
Format rules exist—see current Apple docs. Teams usually prefer integer builds.
How many builds under one marketing version?
Fix process chaos before worrying about limits. Past ~20 builds, rethink testing strategy.
How do live users know a hotfix build shipped?
Users see marketing; support uses build for crashes. Public comms use PATCH when needed.
CI and manual upload collide?
Yes. Designate one build number source (usually CI).
Must extension build match main app?
Follow Apple’s target rules and Xcode prompts; verify with Archive before release.
Must iOS and Android numbers match?
No. Log each side separately so support does not mix them.
Next steps
- Encode monotonic build rules in repo and CI.
- Before next upload, fill iOS release log and check App Store materials.
- For external TestFlight, read external TestFlight and TestFlight review tips.
- Bind rejection flow to rebuild numbering template and rejection fix.
- On dual-store release days, send dual-store alignment table to support.
Related reading
Back to guide library · Apple listing · Telegram @hagee66