CRT/storebound
1
0
Fork 0
Code Issues Pull requests Releases 1 Packages 1 Activity Actions
storebound/skills/appstore-first-release/SKILL.md

10 KiB
Raw Blame History

name description
appstore-first-release Step-by-step first (and later) App Store release of a mobile app or game - App Store Connect API key, bundle id, app record, signing, build and upload with the API key (apple signing, apple build, apple upload), TestFlight, version + listing text in many locales, screenshots, age rating, App Privacy, review details, in-app purchases with the first version, and submitting for review. Use when the user wants to publish, release, upload or set up an iOS app or game on the App Store or TestFlight, or hits App Store Connect API errors.

App Store: first release

The CLI is storebound (on PATH while the plugin is enabled; otherwise bunx storebound in a project that has it, or bun <toolchain>/cli/index.ts; agents can also use the storebound mcp tools). Config: storebound.config.ts; credentials: ASC_KEY_ID, ASC_ISSUER_ID, ASC_P8 (env or .storebound/credentials.json, gitignored). All commands are idempotent and have --dry. Run storebound check first.

Do it, don't ask (first rule in AGENTS.md / docs/agents-core.md of the toolchain): you run every step below yourself, API steps with storebound and UI steps in App Store Connect with your browser tool, and verify each. The owner only presses Submit for Review, Release, App Privacy Publish, cancels a submission or accepts agreements, and answers the compliance facts no file proves, all in one batch at the start.

Steps (API = storebound, UI = App Store Connect, driven by you with your browser tool; Local = this machine)

  1. UI · API key. App Store Connect > Users and Access > Integrations > App Store Connect API > Team Keys > + (Admin or App Manager). Download AuthKey_<KEYID>.p8 once, keep it in ~/.appstoreconnect/private_keys/, note the Key ID and Issuer ID. The same key signs builds (-allowProvisioningUpdates).
  2. API · Bundle id. storebound apple bundle registers it (Certificates, Identifiers & Profiles).
  3. UI · App record. Apps > + > New App: iOS, name, primary language, the bundle id, SKU. No API for this. The name is unique on the App Store: when App Store Connect says it is "already being used", ask the owner for a longer App Store name (30 characters at most, e.g. "STAR DASH: Stone Age to 2100"), set it as apple.name and fill again (storebound console fill apple-app-record). app.name stays the Play and on-device name; apple listing sends apple.name for every locale without its own ### name block, and storebound check flags a name over 30 characters. Then storebound apple status finds it (put the Apple ID in apple.appId to skip the lookup).
  4. Local · Info.plist. ITSAppUsesNonExemptEncryption with the true answer (export-compliance skill; NO only when the app uses nothing beyond OS / HTTPS encryption) so builds arrive answered; NSUserTrackingUsageDescription if ads use the IDFA; privacy policy reachable inside the app (guideline 5.1.1).
  5. Local · Sign, build + upload (Mac with Xcode; the API key signs, no Xcode account login needed). Details and the manual-signing route: build-and-sign skill. 
    storebound apple signing status                 # capabilities, certificate with a key on this Mac, profiles
storebound apple build --version 1.0.0 --dry    # project + scheme found, next build number, ExportOptions.plist
storebound apple build --version 1.0.0          # xcodebuild archive + exportArchive -> build/ios/export/<version>-<build>/*.ipa
storebound apple upload --dry                   # then without --dry (asks): API build upload, waits for VALID
    apple build takes the build number from storebound apple next-build unless --build-number N is given, and prints it at the end: note it, every later step selects that exact build, never "the latest". The generated ExportOptions.plist uses method app-store-connect, destination export, your team and the signing style of apple.signing.style (automatic by default). Processing takes 5-30 min; apple upload waits for it.
  6. API · TestFlight. Put an internal group with allBuilds: true in apple.testflight.groups and run storebound apple testflight groups sync: every new build reaches the team automatically. External testers, What to Test, Test Information and Beta App Review: the testflight skill. Sandbox testers stay UI: Users and Access > Sandbox.
  7. API · Version + text. Fill store/appstore.md, then storebound apple listing --version 1.0.0 --build 3 (version, copyright, MANUAL release, the build with exactly that number, name / subtitle / privacy URL, description / keywords / promo / URLs). Run it with --dry first and show the owner the plan: the version decision (keep, update the editable version's string, create, or refuse with the reason), the build, and per locale create / update with old -> new per field. Locales still marked status=draft / status=translate are skipped until listing reviewed (--include-drafts only when the owner says so). Then run it yourself with --yes: it applies exactly that plan. Then storebound apple release --phased on: manual release + phased release is the default for every version (release-management).
  8. API · Screenshots. store-screenshots skill, then storebound apple screenshots > .storebound/asc-shots.log 2>&1 & (6.9" + 6.5" per locale, MD5-idempotent).
  9. API · App info. storebound apple appinfo (--dry first: old -> new per field): categories, age rating declaration, content rights, Free price, all territories. The first availability record of a new app may be refused by the public API (an error on POST /v2/appAvailabilities); then set it once in App Store Connect > Pricing and Availability with your browser tool and re-run (later runs only read it).
  10. API · Review details. storebound apple review-details (contact from .storebound/credentials.json reviewContact, or --contact-from <Apple ID of another app of the team>; notes from the config). Apps behind a sign-in: the demo account from .storebound/ (review-access skill). Apps with accounts: in-app deletion (account-deletion skill).
  11. API · In-app purchases and subscriptions. store-iap-setup and store-subscriptions skills. First IAPs and subscriptions go to review with this version: storebound apple iap-submit --with-version --dry, then (after the owner's yes, since it submits) storebound apple iap-submit --with-version --yes. On a real first release (2026-10-12) it added the IAPs to the draft submission that already held version 1.0.0 and submitted them, first try. Not the console: its IAP "Add for Review" menu did not react to scripted clicks, and the version page no longer has an "In-App Purchases and Subscriptions" section.
  12. UI · App Privacy. store-declarations skill (nutrition labels; you fill and save them), then the owner presses Publish.
  13. Preflight. storebound validate --apple until it shows no blocker (store-preflight).
  14. Submit. storebound apple submit --build <n> (dry run: the plan table with the build you uploaded, by its number, the version and the ready IAPs in one review submission), then the owner's yes for the same command with --yes; with IAPs apple iap-submit --with-version --yes does the same without attaching a build (step 11). In the desktop app the owner presses Releases > Submit for review (plan, then a system dialog). Release type MANUAL means the owner presses "Release" after approval.
  15. Verify + wait. storebound apple status: version WAITING_FOR_REVIEW, IAPs WAITING_FOR_REVIEW, one review submission. storebound apple status --wait-review polls until approved (exit 0) or rejected (exit 1, review-rejections). Approved: the owner releases (release-management).

Gotchas

  • The app record cannot be created via API; the bundle id can.
  • First consumable / non-consumable IAPs must be submitted together with an app version. The deprecated inAppPurchaseSubmissions answers FIRST_*_MUST_BE_SUBMITTED_ON_VERSION; storebound apple iap-submit --with-version puts both into one review submission through reviewSubmissionItems (worked on a real first release, 2026-10-12). The console route is broken for agents: the IAP "Add for Review" menu ignored scripted clicks and the version page has no "In-App Purchases and Subscriptions" section any more. If the version was already submitted without them: cancel the review submission (storebound apple status --cancel-submission <id>, the owner's yes), wait a minute, then apple iap-submit --with-version (pitfall 28).
  • Rejected (Invalid Binary, a crash, ...): the review submission stays open with UNRESOLVED_ISSUES and keeps the version and its IAPs. Upload a fixed build, then storebound apple resubmit --build <n> (dry run with the plan table), and after the owner's yes --build <n> --yes: it attaches build n, reuses that submission (no second draft), adds only missing items, marks the REJECTED version item resolved (Apple refuses every submit with "not ready to be submitted yet" until it is; IAP items with --resolve-iaps) and resubmits, retrying only while nothing is left REJECTED (pitfall 30, review-rejections). apple iap-submit reuses it the same way. An empty draft (0 items) cannot be canceled and is harmless.
  • App Privacy (data types, purposes, linked, tracking) is UI-only and must be published, not just saved.
  • Export compliance unanswered = "Missing Compliance": storebound apple encryption (export-compliance).
  • ITMS-91053 / 91061 privacy manifest emails after upload: privacy-manifest skill.
  • Screenshot sizes: 6.9" 1320 x 2868 (APP_IPHONE_67) is required; 6.5" 1284 x 2778 (APP_IPHONE_65) recommended. PNG without alpha. Up to 10 per set. Apple processes uploads async; failures show as FAILED later.
  • App Store icon (1024) must have no alpha channel (storebound icons writes rgb24).
  • Limits: name 30, subtitle 30, promotional text 170, keywords 100 characters (not bytes; no spaces after commas), description 4000. No "What's New" on a first version.
  • Guideline 5.1.1: the privacy policy link must be inside the app too (Settings > Privacy), not only in the listing.
  • xcodebuild with Capacitor needs a UTF-8 locale (export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8).
  • 500 / 503 from the API happen; storebound retries with backoff.