references/multi-item-submissions.md
# Multi-item review submissions
Read this reference when one review submission must contain the app version plus versioned digital goods, Game Center components, in-app events, or Asset Library media.
Follow only the section for the current phase:
- During readiness, complete **Prepare every item**, then return to the main release flow.
- Enter **Assemble the submission** only after the app version is staged and the multi-item lane is selected.
- Enter **Submit** only after inspecting the assembled draft and obtaining confirmation.
## Prepare every item
- Resolve the exact `VERSION_ID` and each product or component version ID.
- Use `asc-submission-health` to repair missing IAP, subscription, or subscription-group versions.
- Use `asc-in-app-events` for event readiness and `asc-metadata-sync` for Asset Library delivery and placement checks. Event and library asset IDs are distinct from their localization or placement IDs.
- For releases with Game Center items, confirm the Game Center app version exists:
```bash
asc game-center app-versions list --app "APP_ID" --output table
asc game-center app-versions create --app-store-version-id "VERSION_ID" --output json
```
Create only when the intended Game Center app version is absent.
## Assemble the submission
Do not create a review submission from the readiness gate. Start this phase only after the app version and build are staged and the user has selected the multi-item lane.
Inspect existing submissions before creating one:
```bash
asc review submissions list \
--app "APP_ID" \
--platform IOS \
--include "items,appStoreVersionForReview" \
--paginate \
--output json
```
Branch before writing:
- If `asc-submission-health` or the caller handed off a `SUBMISSION_ID`, inspect it with `asc review submissions-get --id "SUBMISSION_ID" --include "items,appStoreVersionForReview" --output json`. Reuse it only when it is the intended `READY_FOR_REVIEW` draft. If it fails that check, stop and return the mismatch to `asc-submission-health` for diagnosis; do not create another submission or add items.
- With no handed-off ID, if exactly one `READY_FOR_REVIEW` draft matches the intended release, capture and reuse its ID.
- With no handed-off ID, if no matching draft or active submission exists for the intended version or review items, create one and capture its ID:
```bash
asc review submissions-create --app "APP_ID" --platform IOS --output json
```
- Otherwise—when drafts are ambiguous or the intended version or review items belong to another active submission—stop and diagnose through `asc-submission-health`. Do not create a second submission.
Use the reused or newly created ID as `SUBMISSION_ID` below. If neither branch assigned one, do not continue.
List the draft's current items before attaching anything:
```bash
asc review items list --submission "SUBMISSION_ID" --paginate --output json
```
Compare each intended item type and resource ID with the returned relationships. Skip exact matches already attached to this draft. Add only missing items, with the app version first, followed by the resolved product and Game Center version items:
```bash
asc review items add --submission "SUBMISSION_ID" --item-type appStoreVersions --item-id "VERSION_ID"
asc review items add --submission "SUBMISSION_ID" --item-type inAppPurchaseVersions --item-id "IAP_VERSION_ID"
asc review items add --submission "SUBMISSION_ID" --item-type subscriptionVersions --item-id "SUBSCRIPTION_VERSION_ID"
asc review items add --submission "SUBMISSION_ID" --item-type subscriptionGroupVersions --item-id "GROUP_VERSION_ID"
asc review items add --submission "SUBMISSION_ID" --item-type gameCenterLeaderboardVersions --item-id "GC_LEADERBOARD_VERSION_ID"
```
Supported Game Center item types also include:
- `gameCenterAchievementVersions`
- `gameCenterActivityVersions`
- `gameCenterChallengeVersions`
- `gameCenterLeaderboardSetVersions`
Add only types required for this release. Do not submit placeholder or unresolved IDs.
For authorized event or library co-submissions, use `appEvents`,
`appAssetLibraryImages`, or `appAssetLibraryVideos` with the resolved resource ID.
Inspect existing item relationships first, as above. These types do not require a
Game Center app version; run Game Center preparation only when that release uses it.
## Submit
Inspect the assembled submission before the final mutation, then require confirmation:
```bash
asc review submissions-get --id "SUBMISSION_ID" --include items --output table
asc review items list --submission "SUBMISSION_ID" --paginate --output table
asc review submissions-submit --id "SUBMISSION_ID" --confirm
```
If inspection shows an existing active or completed submission instead of the draft being assembled, stop and diagnose through `asc-submission-health` rather than creating another submission.
SKILL.md
---
name: asc-release-flow
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.
---
# App Store release orchestration
Use this skill to carry a release from an approved plan to App Store review.
## Ownership boundary
This skill owns:
- staging metadata and attaching a build;
- publishing an IPA or building locally;
- submitting a prepared version;
- assembling a multi-item review submission.
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.
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.
## Preconditions
- 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.
## Choose the release lane
| 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 |
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.
## Run the readiness gate
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`.
Validate before any submission:
```bash
asc validate --app "APP_ID" --version "1.2.3" --platform IOS --output table
```
Use strict mode when warnings must stop automation:
```bash
asc validate --app "APP_ID" --version "1.2.3" --platform IOS --strict --output table
```
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.
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 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.
## Stage an existing build
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.
Preview metadata-driven staging:
```bash
asc release stage \
--app "APP_ID" \
--version "1.2.3" \
--build-id "BUILD_ID" \
--metadata-dir "./metadata" \
--dry-run \
--output table
```
Apply the reviewed plan:
```bash
asc release stage \
--app "APP_ID" \
--version "1.2.3" \
--build-id "BUILD_ID" \
--metadata-dir "./metadata" \
--confirm
```
`--metadata-dir` takes the canonical metadata root that contains `app-info/` and `version/<version>/`, the same layout as `asc metadata push --dir`. 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.
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.
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.
Structured output includes a `validate_build` step at the start of `steps[]`. Match steps by name rather than array position.
## Submit a prepared version
Use `asc review submit` after metadata, review details, availability, build processing, and product readiness are already resolved.
```bash
asc review submit --app "APP_ID" --version "1.2.3" --build-id "BUILD_ID" --dry-run --output table
asc review submit --app "APP_ID" --version "1.2.3" --build-id "BUILD_ID" --confirm
```
Use `--version-id "VERSION_ID"` instead of `--version` when the exact version ID is known. Select the build with `--build-id`, or with `--build-number "45"` to skip the build-ID lookup; it matches only builds of that app, version string, and platform. Right after an upload, prefer `--build-number` over `--latest`, which can still pick the previous upload. Add `--wait` to wait for processing before attaching.
## Upload or build, then publish
Use `asc publish appstore` when the release starts from an IPA or a local Xcode project/workspace.
Preview an IPA upload and submission:
```bash
asc publish appstore \
--app "APP_ID" \
--ipa "./App.ipa" \
--version "1.2.3" \
--submit \
--dry-run \
--output table
```
Run it after reviewing the plan:
```bash
asc publish appstore \
--app "APP_ID" \
--ipa "./App.ipa" \
--version "1.2.3" \
--submit \
--wait \
--confirm
```
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.
Omit `--submit` when the user wants upload and attachment only.
## Submit multiple review items
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.
## Handoff after submission
Report:
- 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.
Use `asc-submission-health` for monitoring, cancellation, rejection diagnosis, or retry decisions.
## Guardrails
- 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.