shipkit-submit

name	shipkit-submit
description	Automate App Store Connect submission with the asc CLI — install/auth, metadata and screenshot upload, preflight validation, release staging, review submission, and status monitoring. Use when the user asks to submit, ship, release, or publish an app to the App Store.
user-invocable	true

You drive App Store submissions end to end using asc, the App Store Connect CLI (https://github.com/rorkai/App-Store-Connect-CLI). Prefer read-only checks first; every mutating asc command requires --confirm — always show the user what will run before confirming.

Official references (vendored verbatim from the asc skill family): before running any flow below, read the matching document in this skill's references/ directory — asc-cli-usage.md for CLI conventions, asc-release-flow.md for the readiness-first release flow and first-time submission blockers, and asc-submission-health.md for the full pre-submission checklist and error recovery. They are authoritative; this SKILL.md is the quick orchestration path. If richer asc-* skills are installed in this environment (asc-metadata-sync, asc-id-resolver, asc-xcode-build, …), consult them too.

0. Install & authenticate

# Check
asc --version || brew install asc          # or: curl -fsSL https://asccli.sh/install | bash

# Authenticate (API key from https://appstoreconnect.apple.com/access/integrations/api)
asc auth login --name "MyApp" --key-id "KEY_ID" --issuer-id "ISSUER_ID" --private-key ./AuthKey.p8
asc auth status --validate

Env-var fallback for CI: ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY_PATH. ASC_APP_ID sets a default app.

CLI conventions: discover commands with --help at every level; use explicit long flags; --paginate for full listings; output is JSON when piped (--output table for humans).

1. Resolve IDs

asc apps list --output table                 # find APP_ID
asc versions list --app "APP_ID"             # find/verify version
asc builds list --app "APP_ID" --limit 5     # find latest BUILD_ID and processingState

If no build exists yet, build and upload first (Xcode projects):

asc xcode version edit --build-number "NN"   # bump if needed
# archive/export via xcodebuild, then:
asc builds upload --app "APP_ID" --file ./App.ipa

Wait until the build's processingState is VALID before submitting.

2. Sync metadata & screenshots

If /shipkit-aso produced metadata/<locale>/*.txt and /shipkit-screenshots produced screenshots/final/:

asc metadata pull --app "APP_ID"                          # inspect current state first
asc localizations list --version "VERSION_ID"             # check required fields per locale
# apply description/keywords/whatsNew/etc. via asc metadata / localizations commands (see --help)
asc screenshots upload --app "APP_ID" --version "1.2.3" --dir ./screenshots/final

3. Preflight (never skip)

asc submit preflight --app "APP_ID" --version "1.2.3" --platform IOS   # fastest high-signal check
asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table  # deeper audit
# if the app sells digital goods:
asc validate iap --app "APP_ID" --output table
asc validate subscriptions --app "APP_ID" --output table

Triage blockers into three buckets and tell the user which is which:

• API-fixable: build validity/attachment, metadata, screenshots, review details, content rights, encryption, IAP/subscription readiness.
• Web-session-fixable (experimental asc web ...): first availability bootstrap, first-review subscription attach, App Privacy publish.
• Manual: first-time IAP selection on the version page in App Store Connect.

Common first-time fixes:

# Content rights (required for every submission)
asc apps content-rights edit --app "APP_ID" --uses-third-party-content=false

# Encryption: if build has usesNonExemptEncryption=true and app only uses HTTPS/TLS,
# prefer setting ITSAppUsesNonExemptEncryption=NO and rebuilding:
asc encryption declarations exempt-declare --plist "./Info.plist"

# Review details (contact + reviewer notes / demo account)
asc review details-create --version-id "VERSION_ID" \
  --contact-first-name "…" --contact-last-name "…" \
  --contact-email "…" --contact-phone "…" --notes "How to reach the paid features…"

# First-time availability bootstrap (experimental web session)
asc web apps availability create --app "APP_ID" --territory "USA,GBR" --available-in-new-territories true

# First-review subscription attach
asc web review subscriptions attach-group --app "APP_ID" --group-id "GROUP_ID" --confirm

# App Privacy (public API can't verify publish state)
asc web privacy pull/plan/apply/publish …   # or confirm manually at
# https://appstoreconnect.apple.com/apps/APP_ID/appPrivacy

4. Stage, dry-run, submit

# Prepare everything with a manual checkpoint before submission:
asc release stage --app "APP_ID" --version "1.2.3" --build "BUILD_ID" \
  --metadata-dir "./metadata" --confirm

# Rehearse the full pipeline:
asc release run --app "APP_ID" --version "1.2.3" --build "BUILD_ID" \
  --metadata-dir "./metadata" --dry-run --output table

# When clean — ask the user for explicit go-ahead, then:
asc release run --app "APP_ID" --version "1.2.3" --build "BUILD_ID" \
  --metadata-dir "./metadata" --confirm

Submitting for review is outward-facing and hard to reverse — always get the user's explicit confirmation immediately before the final --confirm run.

If extra review items must ride along (e.g. Game Center versions), use the explicit flow instead:

asc review submissions-create --app "APP_ID" --platform IOS
asc review items-add --submission "SUBMISSION_ID" --item-type appStoreVersions --item-id "VERSION_ID"
asc review submissions-submit --id "SUBMISSION_ID" --confirm

5. Monitor / recover

asc submit status --version-id "VERSION_ID"
asc review submissions-list --app "APP_ID" --paginate
asc submit cancel --id "SUBMISSION_ID" --confirm     # fix and re-submit

TestFlight shortcut when the user just wants a beta out: asc publish testflight.

Readiness checklist (report before submitting)

Build VALID + attached · metadata/localizations complete · screenshots per locale · content rights set · encryption resolved · review details present · availability exists · privacy policy URL set (required with IAP/subs) · IAP/subs validated and attached · App Privacy published. Platform variants: --platform MAC_OS | TV_OS | VISION_OS.