Skip to content

migrate-to-4-0.mdx

Latest commit

 

History

History
346 lines (286 loc) · 16.8 KB

migrate-to-4-0.mdx

File metadata and controls

346 lines (286 loc) · 16.8 KB
Raw

Migrate to 4.0

Upgrade automation from the 3.7 command surface to 4.0

Version 4.0 removes the compatibility surfaces that 3.7 kept behind deprecation warnings, changes a small number of defaults and selection rules, and rejects several inputs that older releases accepted and silently ignored. If you have pinned CI jobs, shell scripts, or internal runbooks on 3.x, read this page before you cut over.

Use asc --help and asc <command> --help against the 4.0 binary when updating automation. The CLI is the source of truth.

What changed

  • The deprecated analytics and review compatibility flags are gone.
  • asc builds next-build-number answers from the whole processed build history instead of the single latest build.
  • asc profiles local follows the active Xcode's provisioning profile directory on macOS.
  • Replacing remote screenshots or video previews now requires --confirm.
  • Many flags that were previously accepted and ignored now fail with a usage error before any API call.
  • --device without --create-missing is a temporary exception: 4.x warns and continues to ignore the device IDs; 5.0.0 will reject the combination.

Deprecated signing flag combination

In 3.7, asc signing fetch and asc signing sync push accepted --device without --create-missing, but those device IDs could only be sent to App Store Connect when the command created a profile. Otherwise the value was ignored.

Version 4.x keeps that input working for one deprecation cycle. Both commands print a warning to stderr and continue with the same behavior. Add --create-missing anywhere you pass --device so the IDs can be applied if a profile must be created; 5.0.0 will reject the old combination with a usage error.

asc signing fetch --bundle-id "com.example.app" \
  --profile-type IOS_APP_DEVELOPMENT \
  --device "DEVICE_ID_1,DEVICE_ID_2" \
  --create-missing

asc signing sync push --bundle-id "com.example.app" \
  --profile-type IOS_APP_DEVELOPMENT \
  --repo "git@github.com:team/signing.git" \
  --device "DEVICE_ID_1,DEVICE_ID_2" \
  --create-missing

Removed commands

The deprecated asc review items view ... and asc review items-get ... commands are removed. App Store Connect API 4.4.1 has no item-detail GET endpoint. Running either name now fails with an unknown-command usage error (exit 2). Use the list command instead:

asc review items list --submission "SUBMISSION_ID"

Removed flags

Removed in 4.0 Replacement
asc analytics requests --state ... --access-type ONGOING or --access-type ONE_TIME_SNAPSHOT
asc analytics view --date ... --processing-date
asc review items update --state ... --resolved or --removed
asc review items-update --state ... --resolved or --removed

--state already failed in 3.7 with a message naming the replacement, on both asc analytics requests and asc review items update. In 4.0 none of these flags are registered, so the failure is now a generic Unknown flag: --state (or --date) plus a usage dump, still on stderr with exit code 2.

--date is the one removal that drops working behavior. In 3.7 it still filtered, behind a warning, matching an instance against either reportDate or processingDate locally. --processing-date is forwarded to App Store Connect as filter[processingDate], and there is no reportDate equivalent.

asc analytics requests --app "APP_ID" --access-type ONGOING
asc analytics view --request-id "REQUEST_ID" --processing-date "2024-01-01" --paginate

Removed accepted values

--item-type appStoreVersionExperimentV2, the 3.x singular alias on asc review items-add and asc review items add, is removed. It is rejected with an error naming the canonical value:

asc review items add --submission "SUBMISSION_ID" --item-type appStoreVersionExperimentsV2 --item-id "EXPERIMENT_ID"

Two item types remain rejected exactly as they were in 3.7, with the same targeted guidance: appCustomProductPages (pass an app custom product page version ID with --item-type appCustomProductPageVersions) and appStoreVersionExperimentTreatments (experiment treatments cannot be review submission items).

Changed output

  • asc analytics request, asc analytics request --reuse-existing, and asc analytics requests no longer emit state or createdDate, and the "State" and "Created Date" table columns are gone. API 4.4.1 does not return either attribute, so the JSON keys were already omitted and the columns were already blank; only the table shape changes.
  • asc migrate import --confirm can now print a JSON result with status: "partial" while exiting non-zero, listing failureStage, failure, everything that was applied, and completedStages when at least one stage finished (the key is absent when nothing completed). Automation that treated non-empty stdout as success must check status.
  • asc release stage runs a new validate_build step first, so steps[] gains an entry at index 0. Anything that indexes steps positionally must be updated.
  • asc screenshots apply prints the display-type groups that completed before a failure instead of discarding them, then exits non-zero.
  • Declared asc workflow step outputs keep the JSON number the command printed. A value that previously arrived as "42.00000" is now "42", and large integers no longer lose precision. Remove workarounds such as ${VAR%%.*} or printf reformatting.
  • asc builds next-build-number reports latestProcessedBuildNumber: null when the most recent build carries a zero-style placeholder or an unusable build number, instead of failing.
  • Build upload, app event media, and subscription review-screenshot errors now append App Store Connect's description to the error code, for example ERROR_ITMS_90XXX (Invalid Bundle. ...).
  • Output-file errors changed text for writes routed through the shared safe-write path (for example asc screenshots download and publish outputs): output file already exists: "<path>" and publish output "<path>": <reason>. asc certificates csr and asc xcode-cloud artifacts download keep their previous pathless output file already exists text. errors.Is(err, os.ErrExist) still matches.

Changed defaults and selection rules

Provisioning profile directory

asc profiles local install|list|clean no longer defaults to ~/Library/MobileDevice/Provisioning Profiles on every macOS host. It resolves the active Xcode first:

  • Xcode 16 or newer: ~/Library/Developer/Xcode/UserData/Provisioning Profiles
  • Xcode 15 or older: ~/Library/MobileDevice/Provisioning Profiles

If xcodebuild -version cannot run (Command Line Tools only, or an unaccepted licence), the commands fall back to the legacy directory and print one note to stderr. asc profiles local clean --confirm deletes from the resolved directory, so review your automation before running it on an Xcode 16 host, and pass --install-dir when you want the directory pinned:

asc profiles local list --install-dir "$HOME/Library/MobileDevice/Provisioning Profiles"

Build number selection

asc builds next-build-number, asc publish appstore and asc publish testflight in local-build mode, and asc xcode version bump --next-build-number ... now use the highest positive build number across the fully paginated processed-build history plus in-flight uploads, instead of the number attached to the single most recent build. Apps whose newest build carries a lower number than an older one will see a different, higher answer.

Processed builds whose CFBundleVersion is blank or non-numeric (for example 1.0b2) are skipped with a warning on stderr rather than aborting the command, and the answer is computed from the remaining numeric history. If nothing usable remains, nextBuildNumber falls back to --initial-build-number. Known limitation: an in-flight build upload whose cfBundleVersion is blank or non-numeric still fails the command — the CLI refuses to guess while an upload may hold the next number.

Workflow resume

asc workflow run --resume "RUN_ID" refuses a run that has no successful checkpoint and no retry-enabled failed step, with cannot be resumed: no successful checkpoint or retry-enabled failed step. Run state gains a retry_enabled field, so state written by 3.7 does not carry it. Start a fresh run rather than resuming a 3.x run ID.

Workflow step decoding is also strict now: duplicate retry or timeout keys in a single step resolve last-wins instead of by map iteration order, and unknown keys are rejected.

Screenshot display types

  • asc migrate import classifies Apple Watch, Mac, and 13-inch iPad screenshots instead of aborting the import. A 3840x2160 screenshot without an apple tv or vision pro hint in its file name is now reported as ambiguous.
  • 2048x2732 and 2732x2048 screenshots map only to APP_IPAD_PRO_3GEN_129. asc screenshots plan and asc screenshots apply no longer create or populate the retired APP_IPAD_PRO_129 set, so plannedGroups drops for iPad entries and --replace no longer wipes the legacy set. Passing --device-type IPAD_PRO_129 to asc screenshots upload explicitly is unchanged.

fastlane import

asc migrate import --fastlane-dir ... now honors metadata_path and screenshots_path from the Deliverfile instead of discarding them. A stale path in the Deliverfile will select the wrong directory, and a metadata_path that does not resolve inside the Fastlane directory now fails loudly instead of silently falling back to <fastlane-dir>/metadata. Use --allow-external-metadata or --allow-external-screenshots only when those Deliverfile paths intentionally point outside the selected Fastlane directory.

Deliverfile paths resolve relative to the Deliverfile itself. A Deliverfile written with project-root-relative values — fastlane's common metadata_path "./fastlane/metadata" — resolves to <fastlane-dir>/fastlane/metadata under --fastlane-dir and fails with a no-such-directory error. Change the directives to metadata_path "./metadata" and screenshots_path "./screenshots", or remove them to use the conventional <fastlane-dir>/metadata and <fastlane-dir>/screenshots directories. asc migrate import has no --metadata-dir or --screenshots-dir overrides.

Deliverfile platform "osx" and platform "xros" now resolve, screenshot uploads get the upload timeout (ASC_UPLOAD_TIMEOUT) rather than the 30-second request timeout, and locale directories App Store Connect cannot create (for example metadata/nl, which needs nl-NL) are now caught before the confirmed run: asc migrate validate reports them as errors in its report body (valid: false, non-zero errorCount) while still exiting 0, and asc migrate import --dry-run exits non-zero.

Other defaults

  • asc web apps create --auto-rename truncates the generated retry name by character instead of by byte, so a non-ASCII app name produces a different (correct) name than 3.7 did, which could cut mid-character.
  • asc analytics download sanitizes the instance-ID component of its default filename to [A-Za-z0-9._-], replacing anything else with _.
  • Win-back offer creation no longer sends a subscriptionPricePoint relationship for FREE_TRIAL offers.
  • asc release stage --dry-run reads the checkpoint file. Steps a resume would skip are previewed as would skip (already completed in checkpoint), and a checkpoint whose stored arguments no longer match fails the dry run.
  • asc signing fetch no longer writes, and asc signing sync push no longer pushes, certificates App Store Connect reports as deactivated or expired.

Newly rejected input

These calls exited 0 (or failed later, or silently ignored a flag) in 3.7 and now fail with a usage error before any side effect.

Destructive operations now need --confirm

asc screenshots upload --replace and asc video-previews upload --replace require --confirm. --replace --dry-run is unchanged and needs no --confirm; --confirm without --replace is a usage error.

Flags that were accepted and ignored

  • asc signing fetch --device ... and asc signing sync push --device ... are the transition exception: 4.x warns and ignores the device IDs without --create-missing; 5.0.0 will reject the combination.
  • asc screenshots frame --watch rejects --device, --title, --subtitle, --bg-color, --title-color, --subtitle-color, --output-path, --output-dir, and --name. Set them in the Koubou YAML config instead. An empty --watch-review-dir is rejected too.
  • asc webhooks list --next ... cannot be combined with --app or --limit.
  • asc categories subcategories --next ... and asc accessibility list --next ... cannot be combined with other cursor options.
  • asc game-center matchmaking metrics rule-number-results and rule-errors reject --filter-result and --group-by result; use --filter-queue or --group-by gameCenterMatchmakingQueue.
  • asc pass-type-ids list and asc pass-type-ids view require --include certificates before --certificate-fields or --limit-certificates.
  • asc xcode build rejects explicitly empty values for --configuration, --destination, --derived-data-path, and --result-bundle-path (typically an unset CI variable); asc xcode archive rejects an empty --configuration. Omitting the flags is unchanged.

Stricter values

  • asc background-assets upload-files update --file ... requires --checksum.
  • asc subscriptions offers win-back create ... rejects --price whenever it is passed with --offer-mode FREE_TRIAL, and requires --territory for FREE_TRIAL.
  • asc routing-coverage requires a .geojson file name and validates coordinate ranges and null coordinate components.
  • asc game-center matchmaking rules create|update --weight rejects NaN and infinities.
  • asc certificates csr rejects non-regular and nested output paths.
  • asc notarization rejects non-regular archives and trailing data after the completion XML.
  • Analytics resource identifiers must be a single path segment, so a value like --report-id "ID/instances" is rejected before the request.
  • asc signing fetch fails before creating a provisioning profile when any file it would write already exists, naming the colliding file. There is still no overwrite flag: clean the output directory between runs.
  • asc release stage --metadata-dir ... requires the new --allow-deletes when the metadata plan contains delete operations, in both --dry-run and --confirm runs.
  • Pre-authentication preflights were added or tightened across asc app-clips advanced-experiences create ..., asc versions view --include ..., asc migrate localization payloads, asc app-setup ambiguous localizations, screenshot review targets and source roots, asc notify null Slack blocks, and asc xcode team ID, signing style, and build action combinations.

Validation warnings

asc validate and the asc publish appstore preflight report a new legal.format.copyright_year warning when copyright does not start with the four-digit year the rights were obtained. It is a warning, so those runs still exit 0 unless you pass --strict. Forms such as © 2026 Acme Inc., (c) 2026 Acme, Copyright 2026 Acme, 2019-2026 Acme Inc. and 2026, Acme are all accepted.

Not a breaking change

  • An analytics get alias never existed as a command. 3.7 documented one as a deprecated alias, but the binary only ever registered asc analytics view. Nothing to migrate.
  • ExitHTTPUnprocessable was corrected from 22 to 32 in the source and in the error-handling table. The runtime already returned 32 in 3.7.

Upgrade checklist

  1. Search your repo for --state, --date, review items view, and review items-get, and replace them with the canonical forms above.
  2. Add --confirm to every screenshots upload --replace and video-previews upload --replace invocation. Pair every --device on signing fetch or signing sync push with --create-missing.
  3. Re-check any script that pins a build number: compare ASC_BYPASS_KEYCHAIN=1 asc builds next-build-number --app "APP_ID" against 3.7 output for one app before you rely on it.
  4. On macOS runners, confirm which provisioning profile directory asc profiles local list reports before running clean --confirm.
  5. Re-run CI with the 4.0 binary and verify exit codes, stderr handling, and structured output parsing, especially anything that indexes asc release stage steps or parses numeric workflow step outputs.

Related docs