asc-release-flow

intent

use this skill to answer "is my app ready to submit right now?" and to drive the full app store release flow with the asc cli. the skill guides you through readiness validation, metadata staging, build attachment, review submission, and monitoring. use it when you need explicit control over each release phase or when automation needs to stop before submission, validate, and wait for approval before going live.

inputs

app identity

• APP_ID (app store connect app identifier, required)
• VERSION (semantic version string like "1.2.3", required for most commands)
• VERSION_ID (app store version entity id, optional but speeds lookups)
• BUILD_ID (the specific build to attach, required for submission)
• PLATFORM (IOS, MAC_OS, TV_OS, WATCH_OS, VIS_OS; defaults to IOS)

authentication

• ASC_* environment variables (ASC_ISSUER_ID, ASC_KEY_ID, ASC_PRIVATE_KEY) or run asc auth login first to cache credentials. asc auth login uses OAuth and stores a session token. edge case: auth tokens expire after 20 minutes of inactivity; re-run login if you see 401 errors mid-workflow.

metadata and assets

• canonical metadata in ./metadata/version/VERSION/ when using metadata-driven staging. metadata includes app name, subtitle, description, keywords, support url, marketing url, release notes, category, and rating info.
• screenshots in ./metadata/screenshots/ (or referenced in metadata config).
• review screenshots for iap and subscriptions if selling digital goods.
• app privacy json (pulled or manually populated) when app privacy needs publishing.

external resources

• build must be valid and processing complete in app store connect (asc status will show build state).
• iap, subscription, and game center entities must exist in app store connect before attaching them to a review.
• for first-time submissions, app availability (pricing territories) must exist or be bootstrapped via web session.

edge cases to prepare for

• network timeouts during long uploads; use --wait flag and polling.
• rate limits on asc api (typically 200 requests per minute per team id); batch operations and add retry logic.
• auth expiry mid-workflow; cache credentials or re-authenticate before batch runs.
• build processing delay; asc status shows real-time state; poll until VALID before attaching.
• empty result sets for validate commands (no issues found is success; empty issues list is not an error).

procedure

1. resolve identifiers up front

if you have app name only, look up APP_ID:

asc apps list --output json | grep -i "app-name"

if you have version string only, resolve VERSION_ID:

asc app-store-versions list --app "APP_ID" --output table

if you have ipa file only, upload it first to get BUILD_ID:

asc publish appstore --app "APP_ID" --ipa "./App.ipa" --dry-run --output table

output: APP_ID, VERSION, VERSION_ID (if needed), BUILD_ID (if submitting).

2. validate readiness (blocking check)

run the primary readiness check:

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

examine the output table. success means no blocking issues in the "status" column. if you see warnings and want strict mode:

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

if selling digital goods, add targeted validation:

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

output: validation report (table format shows issue type, severity, and remediation hint).

3. stage without submitting (pre-flight preparation)

when you want to apply metadata, attach build, and prepare the version without submitting for review yet:

preview the staging plan:

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

review the plan table (shows metadata mutations, build attachment, validation results). if the plan looks correct, apply it:

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

alternatively, copy metadata from a prior version instead of loading from disk:

asc release stage \
  --app "APP_ID" \
  --version "VERSION" \
  --build "BUILD_ID" \
  --copy-metadata-from "1.2.2" \
  --confirm

output: staged version with metadata applied and build attached (asc release stage --confirm returns success message and version id).

4. handle first-time blockers (conditional)

see decision points section for full branching logic. apply only the remediation steps your app needs.

5. submit for review

for explicit review submission of an already-staged version:

asc review submit \
  --app "APP_ID" \
  --version "VERSION" \
  --build "BUILD_ID" \
  --dry-run \
  --output table

asc review submit \
  --app "APP_ID" \
  --version "VERSION" \
  --build "BUILD_ID" \
  --confirm

or use VERSION_ID directly if already resolved:

asc review submit \
  --version-id "VERSION_ID" \
  --build "BUILD_ID" \
  --confirm

output: submission id and review submission status (usually "PENDING_REVIEW").

6. one-command upload and submit (alternative to steps 3-5)

when you want upload, build processing, staging, and submission in one high-level call:

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

asc publish appstore \
  --app "APP_ID" \
  --ipa "./App.ipa" \
  --version "VERSION" \
  --submit \
  --confirm

if build processing takes time, add polling:

asc publish appstore \
  --app "APP_ID" \
  --ipa "./App.ipa" \
  --version "VERSION" \
  --submit \
  --wait \
  --confirm

output: build id, submission id, and submission status.

7. monitor submission and cancel if needed

check app-level status:

asc status --app "APP_ID"

check version-specific submission state:

asc submit status --version-id "VERSION_ID"
asc submit status --id "SUBMISSION_ID"

cancel an in-flight submission:

asc submit cancel --id "SUBMISSION_ID" --confirm

output: submission status (PENDING_REVIEW, IN_REVIEW, READY_FOR_SALE, REJECTED, etc.).

decision points

if app has no initial availability record (first submission)

• check: run asc pricing availability view --app "APP_ID". if empty or error, availability does not exist.
• then: bootstrap using web session (public api cannot create initial availability):

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

• after bootstrap: use public api for future edits:

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

• else (availability exists): proceed to validation step 2.

if app sells subscriptions and first review needs a group attached

• check: run asc validate subscriptions --app "APP_ID". if diagnostics pass but submission is blocked, list first-review state:

  asc web review subscriptions list --app "APP_ID"
  

• if group not attached: attach group or single subscription:

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

  or:

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

• for later reviews (not first submission): submit via public api:

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

• else (not first review or no subscriptions): proceed to next section.

if app sells iaps and readiness check reports missing review screenshots or incomplete localization

• check: run asc validate iap --app "APP_ID". if report lists missing review screenshots:

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

• if iap is on a published app: submit via public api:

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

• if this is the first iap on the app or first new iap type: apple may require manual selection on the app version page in web connect. prepare iap with full localization, pricing tiers, and review screenshot data first. then (if cli attach fails or you prefer web flow):

  asc web review iaps attach --app "APP_ID" --iap-id "IAP_ID" --confirm
  

  (note: this requires active authenticated web session; use only for first-version selection gap, not ongoing submissions.)
• else (iaps ready): proceed to next section.

if app integrates game center and review must ship with app-version and leaderboard/achievement versions

• check: run:

  asc game-center app-versions list --app "APP_ID"
  

• if no app-version record for this release, create it:

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

• if game center components must ship together, use explicit submission api:

  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
  

  (also supports gameCenterAchievementVersions, gameCenterActivityVersions, gameCenterChallengeVersions, gameCenterLeaderboardSetVersions.)
• else (no game center): proceed to next section.

if app privacy publish state is unknown or not yet published

• check: asc validate does not fully verify app privacy state. pull current privacy data:

  asc web privacy pull --app "APP_ID" --out "./privacy.json"
  

• view the json. if you want to use cli to plan and apply changes (optional):

  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
  

• else (prefer manual confirm): open browser to https://appstoreconnect.apple.com/apps/APP_ID/appPrivacy and verify "publish" button shows green and ready, or manually publish there.

if review details (contact name, email, phone, demo notes) are incomplete or missing

• check:

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

• if no detail record exists or is incomplete, create or update:

  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."
  

  or update existing:

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

• note: only fill demo-account fields (demo-account-name, demo-account-password) when app review truly needs demo credentials for testing; do not overshare.
• else (details complete): proceed to step 5 or 6.

if readiness validation returns warnings but not blocking errors

• decision: does this app require strict mode (warnings = blockers)?
• if yes: run asc validate --strict and fix all warnings before submission.
• if no (warnings are advisory): proceed to staging step 3.

if staging plan shows dry-run errors

• do not run --confirm. instead, examine the error messages in the dry-run output (table format includes error type and hint). fix root cause (missing metadata file, invalid build id, incomplete pricing) and re-run --dry-run. repeat until plan is clean.

if build is not yet valid (still processing)

• check: asc status --app "APP_ID" shows current build state.
• if build state is "PROCESSING": wait and poll again in 1-5 minutes.
• if build state is "INVALID" or "FAILED": rebuild and re-upload. do not attempt to attach an invalid build to a submission.

if you receive 401 auth errors mid-workflow

• re-authenticate: asc auth login (will prompt for web oauth or use env vars if set).
• retry the command.

output contract

readiness check output

• format: table (asc validate --output table)
• fields: issue-id, issue-type (e.g., "missing-screenshot"), severity (warning, error), item-name, remediation-hint
• success: no rows with severity "error" (warnings may or may not block depending on --strict flag)
• failure: one or more error rows; do not proceed to submission until errors are resolved

staging plan output

• format: table (asc release stage --dry-run --output table)
• fields: action (apply-metadata, attach-build, validate), status (ok, warning, error), detail
• success: all actions show "ok" status; apply with --confirm
• failure: one or more actions show "error" status; fix root cause and retry --dry-run

staged version output

• format: success message with version-id and build-id
• example: "version 1.2.3 (id: ABC123) staged with build XYZ789; ready for submission"
• location: stdout; store version-id and build-id for next step

submission output

• format: json or table (asc review submit --output table)
• fields: submission-id, status (PENDING_REVIEW typical), submitted-at (iso8601 timestamp)
• success: submission-id is non-empty and status is PENDING_REVIEW or similar
• location: stdout; log submission-id for monitoring

monitoring output

• format: table (asc submit status --id "SUBMISSION_ID" --output table)
• fields: submission-id, version, status, submitted-at, decision-date (if decided), decision (if decided)
• success: status advances through PENDING_REVIEW, IN_REVIEW, READY_FOR_SALE, or other terminal state
• failure: status shows REJECTED or DEVELOPER_REJECTED; examine decision field for reason

ready checklist confirmation

• all steps in the "ready checklist" section below should return success (no blocking issues, staged plan clean, build valid, metadata complete, availability exists, digital goods localized and attached, game center items included if needed, app privacy confirmed/published)

outcome signal

validation succeeded: asc validate --app ... --output table returns clean table with no error-level issues, or explicit "readiness: passed" message.

staging succeeded: asc release stage --confirm returns "version X.Y.Z staged successfully" and version-id, build-id are echoed.

submission succeeded: asc review submit --confirm returns non-empty submission-id and status PENDING_REVIEW (or equivalent). you can now monitor submission progress.

submission in-flight: asc submit status --id "SUBMISSION_ID" --output table shows status != "PENDING_REVIEW" (e.g., "IN_REVIEW", "READY_FOR_SALE", "REJECTED"). check decision field for reviewer feedback if terminal state reached.

first-time blocker resolved: after running first-time remediation commands (availability bootstrap, subscription attach, iap attach, game center app-version create, app privacy publish), re-run asc validate; blocker should no longer appear in issue list.

one-command workflow succeeded: asc publish appstore --submit --confirm returns build-id, version-id, and submission-id all non-empty; submission status is PENDING_REVIEW or equivalent.

all checks green: review the ready checklist below. if every item is checked off and no asc commands return errors, the app is release-ready and waiting for app review decision.

ready checklist

an app is effectively ready for submission when:

• asc validate --app "APP_ID" --version "VERSION" --platform IOS returns no error-level issues (warnings ok unless --strict is used)
• asc validate iap --app "APP_ID" returns no blocking issues if app sells iaps
• asc validate subscriptions --app "APP_ID" returns no blocking issues if app sells subscriptions
• asc release stage --dry-run produces a clean plan (all actions "ok" status)
• asc release stage --confirm completes successfully (version-id and build-id confirmed)
• build state is VALID (asc status --app "APP_ID" confirms build.state == "VALID")
• metadata is complete: app name, subtitle, description, keywords, support url, marketing url