wjs-publishing-appstore

Take an iOS app that's already building to TestFlight and ship it to the App Store: prepare the screenshots + description/metadata, then use the existing fastlane to submit for review.

This is the App Store counterpart to wjs-publishing-testflight, which is a prerequisite — that skill owns build / signing (match) / CI / the beta lane. This skill assumes that's done and only adds the listing + a deliberate release lane. Reference implementations: VoiceDrop, Cathier.

Mental model

git push → main      → beta lane    → TestFlight        (unchanged, automatic)
fastlane release     → release lane → metadata + screenshots → submit for review

Submitting to review is high-stakes, so it is never triggered by a push — it is the explicit fastlane release command you run on purpose.

Prerequisites

• wjs-publishing-testflight already set up: match appstore certs, the ASC_API_* secrets, a working beta lane, and at least one build already uploaded to TestFlight (this also creates the App Store Connect app record).
• Apple credentials / ASC API key: see [[apple-developer-credentials]] and the prerequisites table in wjs-publishing-testflight — do not re-list secrets here (this skill auto-publishes to a public repo).
• If the App Store Connect app record does not exist yet, create it once: bundle exec fastlane produce -u jianshuo@hotmail.com -a <BUNDLE_ID> --app_name "<Name>".

Steps

1. Scaffold the metadata tree

scripts/scaffold-metadata.sh        # from this skill; run at the repo root

Creates fastlane/metadata/{zh-Hans,en-US}/*.txt + review_information/ + top-level category/copyright, seeded with editable VoiceDrop copy. Re-running never overwrites existing files.

2. Write the real copy

Edit every .txt. Watch the limits: name 30 · subtitle 30 · keywords 100 (comma-separated, no spaces) · promotional_text 170 · description 4000. Fill in review_information/ (phone, and a demo account only if login is required) and the privacy URL.

The App Store name is globally unique. A short common name ("VoiceDrop") is almost certainly already taken by another account — the submit then dies at upload_to_app_store with "The app name you entered is already being used." This is the display name only; the home-screen name (CFBundleDisplayName) is separate and can stay whatever you like. Pick a distinct string (e.g. add a word or a Chinese suffix — "VoiceDrop 口述"); longer = safer. It's per-locale and changeable in a later version, so it's not permanent.

3. Shoot screenshots

scripts/shoot.sh                    # default: iPhone 16 Pro Max (6.9"), zh-Hans
LOCALE=en-US scripts/shoot.sh       # second locale

Edit drive_screens() in shoot.sh to hit each marketing screen (3–6, named 01_*, 02_*…). It boots a sim, builds, installs, captures into fastlane/screenshots/<locale>/. FRAME=1 adds frameit framing.

Required size: only the 6.9" display (1320×2868) is mandatory and it covers iPhone-only apps. Add a 13" iPad pass only if TARGETED_DEVICE_FAMILY includes iPad (VoiceDrop is iPhone-only → one size).

Mic-permission gotcha: if the app requests microphone/record permission, iOS shows a dialog xcrun simctl privacy grant microphone does not suppress (a real iOS 26 sim limitation). Open Simulator.app, tap 允许/Allow once — the grant persists for the install, so re-running shoot.sh then captures a clean frame. (simctl has no tap; don't try to click it from the script — synthetic clicks via osascript need macOS Accessibility permission the runner lacks.)

Other iOS 26 sim screenshot gotchas:

• To screenshot a screen you can't reach without a tap, temporarily root the app into that view (env-gated DebugRoot), and seed its data via the app's own token (a sim regenerates its synchronizable-Keychain identity on every reinstall — no iCloud account — so injected data under an old identity won't show; on a real device the identity persists).
• The sim paints a faint ghost of TabView labels near the Dynamic Island even for a bare two-tab TabView — a sim-only Liquid Glass artifact, not in your app. Don't chase it; verify on device.

4. Add the release lane

Paste scripts/release_lane.rb into the existing fastlane/Fastfile inside platform :ios do … end. It uploads metadata + screenshots (the TestFlight lane sets skip_metadata/skip_screenshots: true; this lane sets them false), then submit_for_review: true with the encryption/IDFA compliance answers, guarded by guard_not_in_review.

5. Preview, then submit

# dry-run the listing without submitting (writes an HTML preview, no upload):
bundle exec fastlane deliver --skip_binary_upload true --submit_for_review false --force false

# real submit (uses the build already on TestFlight for this version):
bundle exec fastlane release skip_build:true     # reuse the TestFlight build
bundle exec fastlane release                      # or build a fresh one first

Run locally, or via the CI workflow_dispatch if your build.yml routes a appstore choice to fastlane release (see wjs-publishing-testflight Step 3).

Robust two-step ship (what actually worked): git push → the beta lane builds and uploads to TestFlight and waits for Apple to finish processing → then dispatch appstore → fastlane release skip_build:true reuses that already-processed build. Building a fresh binary inside the release lane risks submitting before the build is processed. CI checks out main, so metadata + screenshots must be committed to main before you dispatch.

Un-ignore the screenshots. The TestFlight-only setup often has fastlane/screenshots/ in .gitignore (that flow uses skip_screenshots). This lane uploads them, so they must be committed — remove that ignore line (keep ignoring only frameit extras) or CI uploads nothing.

App Store Connect one-time gotchas (first submission)

These live in the ASC web console, not in fastlane metadata, and fastlane will refuse the submit until they're set. Do all of them once before the first fastlane release — they're sticky (later versions don't need them redone). A submit that hits these fails at the very last step: the metadata + screenshots have already uploaded, so just fix the console items and re-dispatch — nothing is re-uploaded. The real error block lists all the missing attributes at once (violenceCartoonOrFantasy, ageAssurance, contentRightsDeclaration, "App is not eligible for submission until pricing has been set" …).

• Age rating questionnaire — answer all None/No for a utility. Apple expanded this in 2025 (new fields: ageAssurance, parentalControls, messagingAndChat, healthOrWellnessTopics, …) that fastlane's rating config does not fully cover — so do it in the web console, not via fastlane.
• Pricing & Availability — set Price = Free + territories. Until set: "App is not eligible for submission until pricing has been set."
• Content Rights declaration (App Information) — "does not use third-party content" for most apps.
• App Privacy "nutrition label" — declare data collection. VoiceDrop: audio is user content to the user's own store; location is optional/coarse (filename only); Sign in with Apple is an anonymous identifier; no tracking.
• Export compliance — handled by the lane (export_compliance_uses_encryption: false); no console action.
• A build must be attached (the lane does this) before review.

Updating a version that's already in review

guard_not_in_review (and Apple) will block a re-submit while the version is Waiting for Review. To swap in a newer build, fix copy, or add a screenshot: in ASC open the version → "Remove this version from review" (back to editable) → then re-dispatch fastlane release skip_build:true. The new build is selected, metadata + screenshots re-upload, and it resubmits.

Screenshots must match the binary (guideline 2.3.3). Don't put a screenshot of a feature the in-review build lacks — either ship that feature in the build you're submitting, or hold the screenshot for the version that has it.

Verification checklist

• fastlane/metadata/** has no ...FILL_ME... / empty required fields
• fastlane/screenshots/<locale>/ has ≥1 6.9" PNG per locale, named NN_*
• fastlane deliver preview (Step 5 dry-run) renders the listing cleanly
• App Privacy, age rating, pricing set in ASC console
• fastlane release → "Submitted X for App Store review"; a release/X tag exists
• App Store Connect shows the version as Waiting for Review

Common mistakes

Symptom	Fix
Could not find app … on App Store Connect	App record missing → fastlane produce (Step / Prereqs).
"The app name you entered is already being used"	The name is globally taken → pick a unique display name (Step 2).
Submit fails "missing screenshots" / CI uploaded none	No 6.9" screenshot, wrong size, or fastlane/screenshots/ still gitignored (un-ignore it).
Missing violence… / ageAssurance / contentRightsDeclaration / "pricing has been set"	First-submission console items unset → fill age rating, pricing=Free, content rights, App Privacy in the ASC web console once.
Another version is in review / guard_not_in_review tripped	To update an in-review version, "Remove this version from review" in ASC, then re-dispatch.
Keyword field rejected	Keywords must be comma-separated, no spaces, ≤100 chars total.
Wrong build submitted	Use release skip_build:true to reuse the exact TestFlight build for this MARKETING_VERSION.

Files in this skill

• scripts/scaffold-metadata.sh — create the deliver metadata tree (seeded with VoiceDrop copy)
• scripts/shoot.sh — scripted simctl screenshot capture
• scripts/release_lane.rb — the release fastlane lane to paste into your Fastfile