asc-release-flow

SKILL.md

Release flow (readiness-first)

Use this skill when the question is "Can my app be submitted now?" or when the user wants to prepare and submit an App Store version with the current asc command surface.

Preconditions

Resolve APP_ID, version string, VERSION_ID when needed, and BUILD_ID up front.

Ensure auth is configured with asc auth login or ASC_* environment variables.

Have canonical metadata in ./metadata when using metadata-driven staging.

Treat asc web ... commands as optional experimental escape hatches for flows not covered by the public API.

Answer order

Say whether the app is ready right now.

Name the blocking issues.

Separate public-API fixes from web-session or manual fixes.

Give the next exact command to run.

Blockers usually fall into:

API-fixable: build validity, metadata, screenshots, review details, content rights, encryption, version/build attachment, IAP readiness, Game Center version and review-submission items.

Web-session-fixable: initial app availability bootstrap, first-review subscription attachment, App Privacy publish state.

Manual fallback: first-time IAP selection on the app-version page when no CLI attach flow exists, or any flow the user does not want to run through experimental web-session commands.

Canonical current path

1. Readiness check

Use asc validate; the old submit-preflight shortcut is not part of the current CLI.

asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table

Use strict mode when warnings should block automation:

asc validate --app "APP_ID" --version "1.2.3" --platform IOS --strict --output table

For apps selling digital goods, run the product readiness checks too:

asc validate iap --app "APP_ID" --output table
asc validate subscriptions --app "APP_ID" --output table

2. Stage without submitting

Use asc release stage when the user wants to prepare the version, apply/copy metadata, attach the build, and validate, while stopping before review submission.

asc release stage \
  --app "APP_ID" \
  --version "1.2.3" \
  --build "BUILD_ID" \
  --metadata-dir "./metadata/version/1.2.3" \
  --dry-run \
  --output table

Apply the staging mutations after the plan looks correct:

asc release stage \
  --app "APP_ID" \
  --version "1.2.3" \
  --build "BUILD_ID" \
  --metadata-dir "./metadata/version/1.2.3" \
  --confirm

Use --copy-metadata-from "1.2.2" instead of --metadata-dir when carrying metadata forward from an existing version.

3. Submit an already prepared version

Use asc review submit for explicit App Store review submission. It wraps build attachment plus review submission creation.

asc review submit --app "APP_ID" --version "1.2.3" --build "BUILD_ID" --dry-run --output table
asc review submit --app "APP_ID" --version "1.2.3" --build "BUILD_ID" --confirm

Use --version-id "VERSION_ID" instead of --version when you already resolved the exact version ID.

4. One-command upload and submit

Use asc publish appstore when upload/build/local-build and submission should be one high-level flow.

asc publish appstore --app "APP_ID" --ipa "./App.ipa" --version "1.2.3" --submit --dry-run --output table
asc publish appstore --app "APP_ID" --ipa "./App.ipa" --version "1.2.3" --submit --confirm

Add --wait when the command should wait for build processing before attaching/submitting.

5. Monitor and cancel

asc status --app "APP_ID"
asc submit status --version-id "VERSION_ID"
asc submit status --id "SUBMISSION_ID"
asc submit cancel --id "SUBMISSION_ID" --confirm

First-time submission blockers

Initial app availability does not exist

Symptoms:

asc pricing availability view --app "APP_ID" reports no availability.

asc pricing availability edit ... cannot update because there is no existing availability record.

Check:

asc pricing availability view --app "APP_ID"

Bootstrap the first availability record with the experimental web-session flow:

asc web apps availability create \
  --app "APP_ID" \
  --territory "USA,GBR" \
  --available-in-new-territories true

After bootstrap, use the public API for ongoing changes:

asc pricing availability edit \
  --app "APP_ID" \
  --territory "USA,GBR" \
  --available true \
  --available-in-new-territories true

Subscriptions are ready but not attached to first review

Check subscription readiness first:

asc validate subscriptions --app "APP_ID" --output table

If diagnostics report missing metadata, fix those prerequisites before attaching. Common misses are broad pricing coverage, review screenshots, promotional images, and app/build evidence.

List first-review subscription state:

asc web review subscriptions list --app "APP_ID"

Attach a group for first review:

asc web review subscriptions attach-group \
  --app "APP_ID" \
  --group-id "GROUP_ID" \
  --confirm

Attach one subscription instead:

asc web review subscriptions attach \
  --app "APP_ID" \
  --subscription-id "SUB_ID" \
  --confirm

For later reviews, submit subscriptions through the public review path:

asc subscriptions review submit --subscription-id "SUB_ID" --confirm

In-app purchases need review readiness or first-version inclusion

asc validate iap --app "APP_ID" --output table

Upload missing review screenshots:

asc iap review-screenshots create --iap-id "IAP_ID" --file "./review.png"

For IAPs on a published app:

asc iap submit --iap-id "IAP_ID" --confirm

For the first IAP on an app, or the first time adding a new IAP type, Apple may require selecting the IAP from the app version's "In-App Purchases and Subscriptions" section before submitting the app version. Prepare the IAP with localization, pricing, and review screenshot data first.

Game Center needs app-version and review-submission items

asc game-center app-versions list --app "APP_ID"
asc game-center app-versions create --app-store-version-id "VERSION_ID"

If Game Center component versions must ship with the app version, use the explicit review-submission API so all items can be added before submission:

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 items-add --submission "SUBMISSION_ID" --item-type gameCenterLeaderboardVersions --item-id "GC_LEADERBOARD_VERSION_ID"
asc review submissions-submit --id "SUBMISSION_ID" --confirm

asc review items-add also supports gameCenterAchievementVersions, gameCenterActivityVersions, gameCenterChallengeVersions, and gameCenterLeaderboardSetVersions.

App Privacy is still unpublished

The public API can surface privacy advisories, but it cannot fully verify App Privacy publish state.

asc web privacy pull --app "APP_ID" --out "./privacy.json"
asc web privacy plan --app "APP_ID" --file "./privacy.json"
asc web privacy apply --app "APP_ID" --file "./privacy.json"
asc web privacy publish --app "APP_ID" --confirm

If the user avoids experimental web-session commands, confirm App Privacy manually in App Store Connect:

https://appstoreconnect.apple.com/apps/APP_ID/appPrivacy

Review details are incomplete

asc review details-for-version --version-id "VERSION_ID"

Create or update details:

asc review details-create \
  --version-id "VERSION_ID" \
  --contact-first-name "Dev" \
  --contact-last-name "Support" \
  --contact-email "dev@example.com" \
  --contact-phone "+1 555 0100" \
  --notes "Explain the reviewer access path here."

asc review details-update \
  --id "DETAIL_ID" \
  --notes "Updated reviewer instructions."

Only set demo-account fields when App Review truly needs demo credentials.

Ready checklist

An app is effectively ready when:

asc validate --app "APP_ID" --version "VERSION" --platform IOS has no blocking issues.

asc release stage --dry-run produces the expected plan, or asc release stage --confirm has successfully prepared the target version.

The build is VALID and attached to the target version.

Metadata, screenshots, app info, content rights, encryption, age rating, and review details are complete.

App availability exists.

Digital goods have localization, pricing, review screenshots, and any first-review attachments or manual selections handled.

Game Center app-version and component review items are included when needed.

App Privacy is confirmed or published.

Notes

Do not use the legacy submit-preflight, submit-create, or release-run shortcuts; they are not part of the current CLI.

Use asc validate for readiness.

Use asc release stage for pre-submit preparation.

Use asc review submit for explicit App Store review submission.

Use asc publish appstore --submit --confirm for high-level upload plus submission.

Use asc status and asc submit status after submission.