apple-store-submit

name	apple-store-submit
description	Handle Apple App Store rejection emails end-to-end — parse rejection reasons, create a fix plan, implement code changes (privacy strings, entitlements, sandbox), navigate App Store Connect to update metadata, and resubmit. Use when an app receives a rejection or when preparing a first-time submission.
license	MIT
allowed-tools	Bash, Read, Write, Edit
compatibility	Codex, Claude Code, Cursor, GitHub Copilot, Windsurf, Kiro, and other Agent Skills compatible tools. Requires Xcode, an Apple Developer account, and App Store Connect access.
metadata	{"targets":["_source-only"],"author":"Oleg Koval","tags":["apple","app-store","ios","macos","xcode","submission","rejection"]}

🤖 Auto-generated by weekly-pattern-learner · App Store rejection handling workflow observed in FocusNotch App Store session, Jun 2026 (92 user turns covering rejection → plan → code fixes → metadata → resubmit)

Apple App Store Submission & Rejection Handling

Overview

Parse Apple rejection feedback, implement targeted fixes, update App Store Connect metadata, and resubmit — covering the complete cycle from rejection email to approved build.

When to Use

• Apple review team sends a rejection email
• App fails automated pre-review checks (binary rejected at upload)
• Preparing metadata for first-time submission (screenshots, keywords, privacy labels)
• Resolving App Store Connect errors before submitting for review

Workflow

1. Parse the Rejection

Read the full rejection email. Extract and list:

• Guideline numbers violated (e.g., 2.1, 4.2.0, 5.1.1)
• Code-level issues — missing entitlements, incorrect privacy strings, sandbox violations
• Metadata issues — wrong screenshot sizes, subtitle policy, keyword stuffing
• UX issues — crashes described by reviewer, broken flows, missing functionality

Create a numbered fix plan: one item per rejection point, with the type of fix needed.

2. Classify Fixes by Type

Type	Location
Privacy usage strings missing	Info.plist
Entitlement missing/wrong	<AppName>.entitlements
Crash or broken feature	Source code
Screenshots wrong size/content	App Store Connect
Keywords/subtitle/description	App Store Connect
Build number conflict	Xcode + App Store Connect

3. Implement Code Fixes

Privacy permission strings (Info.plist):

<key>NSMicrophoneUsageDescription</key>
<string>Used for voice input during focus sessions.</string>

<key>NSCalendarsUsageDescription</key>
<string>Used to sync tasks with your calendar.</string>

Entitlements (<AppName>.entitlements):

<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.network.client</key>
<true/>
<key>com.apple.security.files.user-selected.read-write</key>
<true/>

Sandbox violations — remove NoEscapeBlock patterns, replace deprecated APIs, use only sandboxed file access via Security-Scoped Bookmarks when needed.

4. Build and Archive

# Clean build
xcodebuild clean \
  -scheme <AppName> \
  -destination 'generic/platform=macOS'

# Archive
xcodebuild archive \
  -scheme <AppName> \
  -archivePath build/<AppName>.xcarchive \
  -destination 'generic/platform=macOS'

# Export for App Store
xcodebuild -exportArchive \
  -archivePath build/<AppName>.xcarchive \
  -exportPath build/export \
  -exportOptionsPlist ExportOptions.plist

Validate codesigning before upload:

codesign --verify --deep --strict --verbose=4 build/export/<AppName>.app
spctl --assess --verbose=4 build/export/<AppName>.app

5. Update App Store Connect Metadata

Navigate: My Apps → [App] → App Store tab

Common metadata fixes:

• App name: max 30 chars
• Subtitle: max 30 chars, no duplicate keywords from the title field
• Keywords: 100-char total limit, comma-separated, no spaces after commas
• Screenshots: exact pixel dimensions per device type (check Apple's current spec)
• Privacy Nutrition Labels: must accurately reflect data collected/linked to user
• Build selection: select the newly uploaded build before submitting

6. Write Reviewer Notes

In the submission form, fill Notes for Reviewer:

• Explain each rejection point and what was changed
• Reference specific guideline numbers: "Addressing 2.1 — added NSMicrophoneUsageDescription to Info.plist"
• If a feature requires special credentials to test, provide test account details

7. Submit and Track

1. Upload via Xcode Organizer → Distribute App → App Store Connect
2. In App Store Connect: select the new build, fill notes, Submit for Review
3. Typical re-review: 24–48h
4. If rejected again: respond in the Resolution Center thread (same case number)
5. Escalate via Resolution Center for policy disagreements — do not open a new submission

Build Number Protocol

Apple rejects builds with a duplicate build number. Increment CFBundleVersion in Info.plist or Xcode target settings before every upload:

# Bump build number (e.g., 9 → 10)
xcrun agvtool new-version -all 10

Verification

• Every rejection guideline number has a corresponding fix in the plan
• xcodebuild archive exits 0 with no warnings about entitlements
• codesign --verify passes
• App Store Connect shows build status as "Ready to Submit"
• Reviewer Notes reference each changed item
• Build number is higher than any previously uploaded build