asc-release-flow · diff
git:20260329.893209f to git:20260910.90d1807
91 added, 271 removed. Audit A to A.
---
name: asc-release-flow
- description: Determine whether an app is ready to submit, then drive the App Store release flow with asc, including first-time submission fixes for availability, in-app purchases, subscriptions, Game Center, and App Privacy.
+ description: Orchestrate App Store releases with asc, including staging a version, uploading or building an artifact, publishing, and submitting for review. Use when the user wants to prepare or execute a release. Keep Game Center item preparation in this skill; route other readiness failures, stuck submissions, cancellation, and retry decisions to asc-submission-health.
---
- # Release flow (readiness-first)
-
- Use this skill when the real question is "Can my app be ready to submit?" and then guide the user through the shortest path to a clean App Store submission, especially for first-time releases.
-
- ## Preconditions
- - Ensure credentials are set (`asc auth login` or `ASC_*` env vars).
- - Resolve app ID, version string, and build ID up front.
- - For lower-level or first-time flows, also be ready to resolve `VERSION_ID`, `SUBMISSION_ID`, `DETAIL_ID`, `GROUP_ID`, `SUB_ID`, `IAP_ID`, and related resource IDs. Use `asc-id-resolver` when needed.
- - Have a metadata directory ready if you plan to use `asc release stage` or `asc release run`.
- - If you use experimental web-session commands, use a user-owned Apple Account session and treat those commands as optional escape hatches, not the default path.
+ # App Store release orchestration
- ## How to answer
- When using this skill, answer readiness questions in this order:
- 1. Is the app ready right now, or not yet?
- 2. What are the blocking issues?
- 3. Which blockers are API-fixable vs web-session-fixable?
- 4. What exact command should run next?
+ Use this skill to carry a release from an approved plan to App Store review. Keep Game Center item preparation here; keep other blocker diagnosis and review recovery in `asc-submission-health`.
- Group blockers like this:
- - API-fixable: build validity, metadata, screenshots, review details, content rights, encryption, version/build attachment, IAP readiness, Game Center version and review-submission setup.
- - Web-session-fixable: initial app availability bootstrap, first-review subscription attachment, App Privacy publish state.
- - Manual fallback: first-time IAP selection from the app-version screen when no CLI attach flow exists, or any flow the user does not want to run through experimental web-session commands.
+ ## Ownership boundary
- ## Canonical path
+ This skill owns:
- ### 1. Fast readiness check
- Run this first when the user wants the quickest answer to "can I submit now?":
+ - staging metadata and attaching a build;
+ - publishing an IPA or building locally;
+ - submitting a prepared version;
+ - assembling a multi-item review submission.
- ```bash
- asc submit preflight --app "APP_ID" --version "1.2.3" --platform IOS
- ```
+ Use [the preparation section](references/multi-item-submissions.md#prepare-every-item) for Game Center item preparation or attachment blockers. Use that reference's assembly and submission sections only after the app version is staged and the multi-item lane is selected. Switch to `asc-submission-health` for other validation blockers, a stuck submission, cancellation, or retry decisions.
- This is the fastest high-signal readiness check and prints fix guidance without mutating anything.
+ Switch skills within the current task, preserving resolved targets, authorization, and verified progress. A failing gate blocks dependent mutations, not diagnosis or independent authorized work. Continue authorized repairs and resume this flow; request new authority only when repairs exceed the agreed scope.
- ### 2. Real staging pass without submit
- Run this when the user wants the version prepared in App Store Connect but wants a manual checkpoint before creating a review submission:
+ ## Preconditions
- ```bash
- asc release stage \
- --app "APP_ID" \
- --version "1.2.3" \
- --build "BUILD_ID" \
- --metadata-dir "./metadata/version/1.2.3" \
- --confirm
- ```
+ - Resolve `APP_ID`, the version string, `VERSION_ID` when needed, and `BUILD_ID` when a build already exists.
+ - Configure auth with `asc auth login` or `ASC_*` environment variables.
+ - Confirm the intended platform. Use `IOS` unless the app targets another platform.
+ - Keep canonical metadata in `./metadata` when the workflow applies metadata.
+ - Require a dry run before a mutating high-level command, then require `--confirm` for submission.
- Use `--copy-metadata-from "1.2.2"` instead of `--metadata-dir` when you want to carry metadata forward from an existing version. `asc release stage` requires exactly one metadata source and stops before submit.
+ ## Choose the release lane
- ### 3. Full-pipeline dry run
- Run this when the user wants one command that approximates the whole release path:
+ | Intent | Command |
+ | --- | --- |
+ | Prepare metadata and attach an existing build without submitting | `asc release stage` |
+ | Submit an already prepared version | `asc review submit` |
+ | Upload an IPA or build locally, then optionally submit | `asc publish appstore` |
+ | Submit the app version with IAP, subscription, or Game Center version items | lower-level `asc review` submission commands |
- ```bash
- asc release run \
- --app "APP_ID" \
- --version "1.2.3" \
- --build "BUILD_ID" \
- --metadata-dir "./metadata/version/1.2.3" \
- --dry-run \
- --output table
- ```
+ Do not mix lanes after one has already created a review submission. Inspect the existing submission first and continue through the matching lower-level commands.
- This is the best single-command rehearsal for:
- 1. ensuring or creating the version
- 2. applying metadata and localizations
- 3. attaching the build
- 4. running readiness checks
- 5. confirming the submission path is coherent
+ ## Run the readiness gate
- Add `--strict-validate` when you want warnings treated as blockers.
+ Apply this gate to a version that already has the intended build attached. For the staging lane, first complete [Stage an existing build](#stage-an-existing-build); `asc release stage` attaches the build and runs validation, after which this gate can be evaluated. Do not route an expected pre-staging "build not attached" result to `asc-submission-health`.
- ### 4. Deep API readiness audit
- Run this when the user needs a fuller version-level checklist than `submit preflight`:
+ Validate before any submission:
```bash
asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table
```
- Prefer the version string form here so it stays aligned with `asc submit preflight` and `asc release run`. Switch to `VERSION_ID` only for lower-level commands that explicitly require it.
-
- If the app sells digital goods, also run:
-
- ```bash
- asc validate iap --app "APP_ID" --output table
- asc validate subscriptions --app "APP_ID" --output table
- ```
-
- In current asc, `asc validate subscriptions` expands `MISSING_METADATA` into per-subscription diagnostics. Use it to pinpoint missing review screenshots, promotional images, pricing or availability coverage, offer readiness, and app/build evidence before you retry submission or `attach-group`.
-
- When territory coverage is wrong, the newest diagnostics name the exact missing territories instead of only reporting count mismatches. Use `--output json --pretty` when you want machine-readable diagnostics.
-
- ### 5. Actual submit
- When the dry run looks clean:
-
- ```bash
- asc release run \
- --app "APP_ID" \
- --version "1.2.3" \
- --build "BUILD_ID" \
- --metadata-dir "./metadata/version/1.2.3" \
- --confirm
- ```
-
- ## First-time submission blockers
-
- ### 1. Initial app availability does not exist yet
- Symptoms:
- - `asc pricing availability view --app "APP_ID"` reports no availability
- - `asc pricing availability edit ...` fails because it only updates existing availability
-
- Check:
-
- ```bash
- asc pricing availability view --app "APP_ID"
- ```
-
- Bootstrap the first availability record with the experimental web-session flow:
-
- ```bash
- asc web apps availability create \
- --app "APP_ID" \
- --territory "USA,GBR" \
- --available-in-new-territories true
- ```
-
- After bootstrap, use the normal public API command for ongoing updates:
+ Use strict mode when warnings must stop automation:
```bash
- asc pricing availability edit \
- --app "APP_ID" \
- --territory "USA,GBR" \
- --available true \
- --available-in-new-territories true
+ asc validate --app "APP_ID" --version "1.2.3" --platform IOS --strict --output table
```
- ### 2. Subscriptions are READY_TO_SUBMIT but not attached to first review
- For apps with subscriptions, check readiness explicitly:
+ Digital goods are a hard gate. If the release includes IAPs or subscriptions, stop and run the relevant product checks in `asc-submission-health`. Resume this flow only after those checks have no blocking issues and the intended product versions are prepared.
- ```bash
- asc validate subscriptions --app "APP_ID" --output table
- ```
+ For Game Center items, complete only [Prepare every item](references/multi-item-submissions.md#prepare-every-item), then return to this flow. Do not assemble or submit the multi-item review submission during readiness.
- If the validator shows `MISSING_METADATA`, read the row-level diagnostics literally. The newest CLI surfaces missing promotional images, review screenshots, pricing or availability coverage, offer readiness, and app/build evidence in one matrix, which is the quickest way to understand why first-review attach still fails.
+ If app validation reports a Game Center item blocker, stop and use that preparation section. If the only blocker is an unattached build in the staging lane, continue to the staging section. For every other blocker, pause dependent release actions and use `asc-submission-health`; resume after authorized repairs pass validation.
- List current first-review subscription state:
+ ## Stage an existing build
- ```bash
- asc web review subscriptions list --app "APP_ID"
- ```
+ Use `asc release stage` to verify the selected build belongs to the app before changing the version, apply or copy metadata, attach the build, and run validation without creating a review submission.
- If the app is going through its first review and the group needs attaching:
+ Preview metadata-driven staging:
```bash
- asc web review subscriptions attach-group \
+ asc release stage \
--app "APP_ID" \
- --group-id "GROUP_ID" \
- --confirm
+ --version "1.2.3" \
+ --build "BUILD_ID" \
+ --metadata-dir "./metadata/version/1.2.3" \
+ --dry-run \
+ --output table
```
- If `attach-group` still returns `MISSING_METADATA`, fix the validator-reported prerequisites first. The most common misses are broad pricing coverage and a subscription promotional image.
-
- For one subscription instead of a whole group:
+ Apply the reviewed plan:
```bash
- asc web review subscriptions attach \
+ asc release stage \
--app "APP_ID" \
- --subscription-id "SUB_ID" \
+ --version "1.2.3" \
+ --build "BUILD_ID" \
+ --metadata-dir "./metadata/version/1.2.3" \
--confirm
```
- For later reviews, use the normal submission path:
-
- ```bash
- asc subscriptions review submit --subscription-id "SUB_ID" --confirm
- ```
-
- If review artifacts are missing, upload them before submission:
-
- ```bash
- asc subscriptions review screenshots create --subscription-id "SUB_ID" --file "./screenshot.png"
- asc subscriptions images create --subscription-id "SUB_ID" --file "./image.png"
- ```
-
- Also make sure the app’s privacy policy URL is populated when the app sells subscriptions.
-
- ### 3. In-App Purchases need review readiness or first-version inclusion
- For apps with one-time purchases, consumables, or non-consumables, check readiness explicitly:
-
- ```bash
- asc validate iap --app "APP_ID" --output table
- ```
-
- If the IAP is missing its App Review screenshot:
-
- ```bash
- asc iap review-screenshots create --iap-id "IAP_ID" --file "./review.png"
- ```
-
- For IAPs on a published app, submit them directly:
-
- ```bash
- asc iap submit --iap-id "IAP_ID" --confirm
- ```
-
- If this is the first IAP for the app, or the first time adding a new IAP type, Apple requires it to be included with a new app version. Current `asc` commands can validate and submit published-app IAPs, but there is no equivalent first-review attach flow like the subscription web commands yet. In that case:
- - prepare the IAP with `asc validate iap`, pricing, localization, and review screenshot data first
- - then select the IAP from the app version’s “In-App Purchases and Subscriptions” section in App Store Connect before submitting the app version
-
- Also make sure the app’s privacy policy URL is populated when the app sells IAPs.
+ Use `--copy-metadata-from "1.2.2"` instead of `--metadata-dir` when carrying localization metadata forward. Add `--strict-validate` when warnings should fail the stage.
- ### 4. Game Center is enabled but the app version or review submission is incomplete
- If the app uses Game Center, make sure the App Store version is Game Center-enabled:
+ If the metadata plan contains deletes, the dry run and confirmed run both require `--allow-deletes`. Review those deletes first; the flag also disables fallback to an existing locale when that locale is absent locally.
- ```bash
- asc game-center app-versions list --app "APP_ID"
- asc game-center app-versions create --app-store-version-id "VERSION_ID"
- ```
+ Use `--routing-coverage-file "./coverage.geojson"` when the release includes routing app coverage. This experimental step validates the GeoJSON before mutation and stages it before readiness checks.
- If you are adding Game Center components for the first time, include them in the same submission as the app version. Resolve component version IDs first:
+ Structured output includes a `validate_build` step at the start of `steps[]`. Match steps by name rather than array position.
- ```bash
- asc game-center achievements v2 versions list --achievement-id "ACH_ID"
- asc game-center leaderboards v2 versions list --leaderboard-id "LEADERBOARD_ID"
- asc game-center challenges versions list --challenge-id "CHALLENGE_ID"
- asc game-center activities versions list --activity-id "ACTIVITY_ID"
- ```
+ ## Submit a prepared version
- Then use the review-submission flow so you can add the app version and the Game Center component versions to the same submission:
+ Use `asc review submit` after metadata, review details, availability, build processing, and product readiness are already resolved.
```bash
- 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 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
```
- `asc review items-add` also supports `gameCenterAchievementVersions`, `gameCenterActivityVersions`, `gameCenterChallengeVersions`, and `gameCenterLeaderboardSetVersions`.
+ Use `--version-id "VERSION_ID"` instead of `--version` when the exact version ID is known. `--build` may be omitted only when the intended build is already attached and verified.
- If Game Center component versions need to ship with the app version, prefer the explicit `asc review submissions-*` flow over `asc release run --confirm`, because you need a chance to add all submission items before final submit.
+ ## Upload or build, then publish
- ### 5. App Privacy is still unpublished
- The public API can warn about App Privacy readiness but cannot fully verify publish state.
+ Use `asc publish appstore` when the release starts from an IPA or a local Xcode project/workspace.
- If `asc submit preflight`, `asc validate`, or `asc release run` surfaces an App Privacy advisory, reconcile it with:
+ Preview an IPA upload and submission:
```bash
- 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 does not want the experimental web-session flow, confirm App Privacy manually in App Store Connect:
-
- ```text
- https://appstoreconnect.apple.com/apps/APP_ID/appPrivacy
+ asc publish appstore \
+ --app "APP_ID" \
+ --ipa "./App.ipa" \
+ --version "1.2.3" \
+ --submit \
+ --dry-run \
+ --output table
```
- ### 6. Review details are incomplete
- Check whether the version already has review details:
+ Run it after reviewing the plan:
```bash
- asc review details-for-version --version-id "VERSION_ID"
+ asc publish appstore \
+ --app "APP_ID" \
+ --ipa "./App.ipa" \
+ --version "1.2.3" \
+ --submit \
+ --wait \
+ --confirm
```
- If needed, create or update them:
-
- ```bash
- 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."
- ```
+ For local-build mode, provide `--workspace` or `--project` with `--scheme` instead of `--ipa`. Use `--metadata-dir` when the publish command should apply canonical version metadata after ensuring the version.
- ```bash
- asc review details-update \
- --id "DETAIL_ID" \
- --notes "Updated reviewer instructions."
- ```
+ Omit `--submit` when the user wants upload and attachment only.
- Only set `--demo-account-required=true` when App Review truly needs demo credentials.
+ ## Submit multiple review items
- ## Practical readiness checklist
- An app is effectively ready to submit when:
- - `asc submit preflight --app "APP_ID" --version "VERSION"` reports no blocking issues
- - `asc validate --app "APP_ID" --version "VERSION"` is clean or only contains understood non-blocking warnings
- - `asc release stage --confirm` successfully prepared the target version when you want a real pre-submit checkpoint
- - `asc release run ... --dry-run` produces the expected plan
- - the build is `VALID` and attached to the target version
- - metadata, screenshots, and localizations are complete
- - content rights and encryption requirements are resolved
- - review details are present
- - app availability exists
- - if the app has IAPs or subscriptions, the privacy policy URL is present
- - if the app has IAPs, they have localization/pricing/review screenshots and first-time IAPs are selected with the app version
- - subscriptions, if any, are attached for first review or already submitted through the supported review path
- - if the app uses Game Center, the app version is Game Center-enabled and any required Game Center component versions are in the same review submission
- - any App Privacy advisory has been resolved through `asc web privacy ...` or manual confirmation
+ Read [references/multi-item-submissions.md](references/multi-item-submissions.md) when the app version must ship with versioned IAP, subscription, subscription-group, or Game Center items. Add only items the user has resolved and inspected.
- ## Lower-level fallback
- Use the lower-level flow only when the user needs explicit control over each step:
+ ## Handoff after submission
- ```bash
- asc versions attach-build --version-id "VERSION_ID" --build "BUILD_ID"
- asc submit preflight --app "APP_ID" --version "1.2.3" --platform IOS
- asc submit create --app "APP_ID" --version "1.2.3" --build "BUILD_ID" --confirm
- asc submit status --version-id "VERSION_ID"
- # or, if you captured the review submission ID:
- asc submit status --id "SUBMISSION_ID"
- ```
+ Report:
- If the submission needs multiple review items, such as Game Center component versions, use the review-submission API directly instead:
+ - the app, version, platform, build, and submission IDs;
+ - which lane ran and whether it completed;
+ - mutations performed under the user's authorization;
+ - the exact command to monitor the resulting submission.
- ```bash
- 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 gameCenterChallengeVersions --item-id "GC_CHALLENGE_VERSION_ID"
- asc review submissions-submit --id "SUBMISSION_ID" --confirm
- ```
+ Use `asc-submission-health` for monitoring, cancellation, rejection diagnosis, or retry decisions.
- ## Platform notes
- - Use `--platform MAC_OS`, `TV_OS`, or `VISION_OS` as needed.
- - For macOS, upload the `.pkg` separately, then use the same readiness and submission flow.
- - `asc publish testflight` is still the fastest TestFlight shortcut, but for App Store readiness prefer `asc submit preflight`, `asc release stage`, and `asc release run`.
+ ## Guardrails
- ## Notes
- - `asc release stage --confirm` is the safest one-command way to prepare a version without submitting it.
- - `asc release run --dry-run` is the closest thing to a one-command answer for "will this full release flow work?"
- - `asc submit preflight` is the fastest first pass.
- - `asc validate` is the deeper API-side checklist for version readiness.
- - `asc validate subscriptions` now exposes much richer per-subscription diagnostics for `MISSING_METADATA` readiness failures.
- - Web-session commands are experimental and should be presented as optional escape hatches when the public API cannot complete the first-time flow.
- - First-time app-availability bootstrap now goes through the experimental `asc web apps availability create` flow or App Store Connect itself.
- - First-review subscriptions have a concrete CLI attach path; first-review IAP selection still may require the App Store Connect version UI.
- - Game Center can require explicit review-submission item management when components must ride with the app version.
- - If the user asks "why did submission fail?" map the failure back into the three buckets above: API-fixable, web-session-fixable, or manual fallback.
+ - Do not use removed `submit-preflight`, `submit-create`, or `release-run` shortcuts.
+ - Do not add `--confirm` until the dry-run plan matches the requested release.
+ - Do not create a second review submission when one already exists for the version.
+ - Do not turn a validation failure into a partial release; stop at the failing gate.
+ - Keep data on stdout and diagnostics on stderr when wrapping commands in automation.