Skip to main content
TestFlight and beta distribution Level: Developer 10 min read

App Store Version vs Build Numbering Rules for Automated Pipelines

Master CFBundleShortVersionString and CFBundleVersion rules for App Store Connect, TestFlight, and automated CI/CD and AI agent build pipelines.

Published: 2026-11-01 • Last Updated: 2026-11-01 • Author: Kip Lawrence
Key MCP Tools: builds_listapp_store_versions_list

When automating iOS builds or working with AI coding assistants, few issues disrupt a release pipeline as quickly as version number formatting errors. Apple enforces strict formatting rules and monotonicity constraints across every binary uploaded to App Store Connect.

Navigating these rules is a hybrid workflow. Your project's version numbers live inside local source configuration files (Info.plist, pubspec.yaml, or app.json), while Apple's validation checks run against the remote ingestion history in App Store Connect. FlightDeck does not modify your local project files directly; instead, your AI coding assistant inspects your local configuration, uses FlightDeck to query remote build records, compares both sources of truth, and updates your local project settings before you compile.


What You Need

Before configuring version numbers for automated builds:

  • An active Apple Developer account and an application record in App Store Connect.
  • FlightDeck installed and connected to your Apple Developer account.
  • An AI coding assistant (Cursor, Claude Code, Antigravity, Windsurf, or Roo Code) connected to FlightDeck's MCP server. See Connecting Cursor to App Store Connect.
  • Access to your local project codebase (Xcode, Flutter, or React Native / Expo).

The Dual Versioning System: Marketing Version vs. Build Number

Every iOS application bundle defines two distinct version keys inside its Info.plist:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                        iOS Application Bundle                          │
│                               Info.plist                               │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
         ┌─────────────────────────┴─────────────────────────┐
         ▼                                                   ▼
┌─────────────────────────────────┐ ┌─────────────────────────────────┐
│   CFBundleShortVersionString    │ │         CFBundleVersion         │
├─────────────────────────────────┤ ├─────────────────────────────────┤
│ • "Marketing Version"           │ │ • "Build Number" / Machine Counter│
│ • Displayed to public on Store  │ │ • Displayed in TestFlight & logs│
│ • Example: "1.2.0"              │ │ • Example: "48" or "1.2.0.48"   │
│ • Max 18 characters, 3 integers │ │ • Max 18 characters, 3 integers │
│ • Linked to App Store Release   │ │ • Must strictly increment       │
└─────────────────────────────────┘ └─────────────────────────────────┘

1. CFBundleShortVersionString (Marketing Version)

  • What It Represents: The public-facing release version displayed to users on the App Store product page (for example, "Version 1.2.0").
  • Format Requirements:
  • Up to three period-separated non-negative integers: [0-9]+(\.[0-9]+){0,2} (e.g., 1, 1.2, or 1.2.3).
  • Contains only numeric digits (0-9) and periods (.).
  • Avoid leading zeros: Always use 1.2.0, not 1.02.0. Apple parsers strip leading zeros or flag them as malformed integers (ITMS-90056).
  • No alphabetical characters, pre-release tags, hyphens, or git hashes (e.g., 1.0.0-beta.1 is strictly forbidden).
  • Maximum string length of 18 characters.
  • App Store Connect Resource: Corresponds directly to the App Store Version resource (appStoreVersions).

2. CFBundleVersion (Build Number)

  • What It Represents: The internal machine build counter identifying a specific compiled binary. Visible in TestFlight, Xcode Organizer, and crash telemetry.
  • Format Requirements:
  • Up to three period-separated non-negative integers (e.g., 45 or 1.2.0.45).
  • Contains only numeric digits and periods. Maximum 18 characters. Avoid leading zeros.
  • Monotonicity Rule: For a given CFBundleShortVersionString, every new binary uploaded to App Store Connect must have a strictly higher CFBundleVersion than any prior upload for that version.

Feature Matrix: Version vs. Build Rules

Attribute CFBundleShortVersionString CFBundleVersion
Common Name Marketing Version Build Number / Machine Counter
Visible on Public App Store? Yes (in version history and product page) No (visible only in TestFlight & diagnostics)
Allowed Characters Numbers (0-9) and periods (.) Numbers (0-9) and periods (.)
Allowed Segment Count 1 to 3 integers (X, X.Y, X.Y.Z) 1 to 3 integers (X, X.Y, X.Y.Z)
Maximum String Length 18 characters 18 characters
Leading Zero Guidance Avoid leading zeros (1.2.0, not 1.02.0) Avoid leading zeros (42, not 042)
Monotonicity Requirement Increments on public release Must strictly increment with every upload to same version
Transporter Failure Code ITMS-90056 (Malformed format) ITMS-90189 (Duplicate) / ITMS-90062 (Not higher)


Monotonicity Strategy: Per-Version vs. Global Increment

A common architectural question is whether build numbers can be reset back to 1 when creating a new marketing version (e.g., releasing 1.0.0 (42) and then uploading 1.1.0 (1)).

  • Apple Ingestion Specification: Apple validates build monotonicity per marketing version. Uploading 1.1.0 (1) is accepted by App Store Connect even if 1.0.0 (42) was previously ingested.
  • Why Global Monotonicity Is Recommended: 1. TestFlight Caching: TestFlight client update heuristics can misinterpret 42 as newer than 1, confusing beta testers or suppressing update prompts. 2. Crash Analytics: Platforms like Sentry, Datadog, and Firebase Crashlytics index stack traces by build number. Reusing build 1 creates ambiguous release boundaries in error telemetry. 3. Continuous Integration Simplicity: Monotonic counters derived from CI runners (e.g., GitHub Actions run numbers) prevent ingestion race conditions entirely.

Best Practice: Maintain a single, globally increasing integer counter (e.g., 101, 102, 103...) across the entire lifespan of the app, regardless of marketing version bumps.


Configuring Versions Across Frameworks

1. Native Xcode Projects

In modern Xcode projects, versioning is controlled via target Build Settings:

  • MARKETING_VERSION: Controls CFBundleShortVersionString (e.g., 1.2.0).
  • CURRENT_PROJECT_VERSION: Controls CFBundleVersion (e.g., 43).

To update via command-line tools:

BASH
# Update marketing version
xcrun agvtool new-marketing-version 1.2.0

# Increment build number automatically
xcrun agvtool next-version -all

2. Flutter Projects

Flutter configures iOS versions in pubspec.yaml via the version field formatted as <marketing>+<build>:

YAML
name: habit_tracker
description: "A Flutter productivity application"
# Format: <CFBundleShortVersionString>+<CFBundleVersion>
version: 1.2.0+43

When compiling with flutter build ipa, Flutter maps 1.2.0 to CFBundleShortVersionString and 43 to CFBundleVersion. You can also override these dynamically during CI execution:

BASH
flutter build ipa --release --build-name=1.2.0 --build-number=43

3. React Native and Expo Projects

In Expo applications, versions are declared in app.json:

JSON
{
  "expo": {
    "name": "HabitTracker",
    "slug": "habit-tracker",
    "version": "1.2.0",
    "ios": {
      "bundleIdentifier": "com.example.habittracker",
      "buildNumber": "43"
    }
  }
}

For Expo Application Services (EAS) cloud builds, configure eas.json to manage build numbers automatically:

JSON
{
  "build": {
    "production": {
      "autoIncrement": true
    }
  }
}

Verifying Build History and Updating Versions with Your AI Assistant

Because FlightDeck does not alter local project source files, your AI assistant bridges the gap between your local codebase and remote App Store Connect build history.

MERMAID
flowchart TD
    A["Developer Prompt in AI Chat"] --> B["AI Assistant Queries builds_list via FlightDeck"]
    B --> C["FlightDeck Returns Highest Ingested Build Number"]
    C --> D["AI Assistant Inspects Local Config (pubspec/app.json/Xcode)"]
    D --> E["AI Assistant Proposes Next Valid Version"]
    E --> F["AI Assistant Edits Local Config via Local File Tools"]
    F --> G["Developer Compiles Binary with Confidence"]

Step 1: Prompt Your AI Assistant to Audit Version State

Ask your assistant to compare your local configuration against remote App Store Connect records:

TEXT
Inspect our local project configuration for [App Name] to find our current version and build number. Then query App Store Connect through FlightDeck to find the highest build number currently uploaded for this marketing version. Compare them, tell me if our local build number is safe to upload, and suggest the next valid build number.

What Your Assistant Does Behind the Scenes:

  1. It reads your local project file (pubspec.yaml, app.json, or project.pbxproj) to extract the current local version strings.
  2. It queries App Store Connect using FlightDeck's builds_list tool to inspect all ingested binaries for the target application.
  3. It identifies the highest recorded CFBundleVersion currently on Apple's servers.
  4. It compares the two values. If the local build number is less than or equal to the remote build number, it flags the conflict before any compilation or upload attempt.

Step 2: Prompt Your Assistant to Update Local Settings

Once the assistant reports the highest ingested build number, ask it to increment your local project settings:

TEXT
Our latest remote build on App Store Connect is build 42. Please update our local project configuration to increment our build number to 43 while keeping the marketing version at 1.2.0.

Your AI assistant modifies your local pubspec.yaml, app.json, or Xcode configuration using standard file editing capabilities, ensuring your next build archive is ready for ingestion.


Verify Success: Pre-Upload Binary Inspection

After building your release archive (.ipa), ask your AI assistant to verify that the generated binary reflects the updated version numbers:

TEXT
Inspect the compiled IPA archive at [path/to/archive.ipa] using FlightDeck. Verify that CFBundleShortVersionString is "1.2.0" and CFBundleVersion is "43" before we upload.

FlightDeck inspects the local application bundle inside the archive, verifying that both keys are syntactically well-formed, contain no prohibited characters, and satisfy Apple's formatting rules.


Troubleshooting Common Versioning Errors

1. Transporter Error ITMS-90189: "Redundant Binary Upload"

  • Cause: You uploaded a binary with a CFBundleVersion identical to a build that already exists for that marketing version.
  • Fix: Increment CFBundleVersion in your local project settings by at least 1, recompile, and re-upload.

2. Transporter Error ITMS-90062: "CFBundleVersion Must Be Greater"

  • Cause: The uploaded CFBundleVersion is numerically lower than a previously ingested build for the same marketing version.
  • Fix: Query App Store Connect via FlightDeck to find the exact highest build number on record, then set your local build number higher.

3. Transporter Error ITMS-90056: "Malformed Version String"

  • Cause: Your version string contains letters, hyphens, git hashes, or more than three integer segments (e.g., 1.0.0-rc1 or 1.0.0.12.3).
  • Fix: Restrict strings strictly to numbers and periods, formatted as up to three segments (1.2.0).

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