Skip to content

deonmenezes/mobile-app-skill / skills/app-store-release

app-store-release

Unverified

Ship an iOS app update or a first release to the App Store end to end, the way it is actually done across many real releases. Bumps the version, builds and signs on a Mac over SSH (or on a GitHub-hosted Mac when yours is asleep), uploads, waits for processing, submits for App Review, watches the review, handles rejections and hotfixes, and checks the app is really on sale afterwards. Includes its own scripts for Windows, Linux and macOS (what has and has not been exercised is listed in the skill), and a one-time setup interview so later releases need no questions. Use when the user says "ship it", "release an update", "push a new version", "submit to the App Store", "upload to TestFlight", "resubmit", "replace the build in review", "my app got rejected", "hotfix", "why is my approved app not on the store", or "set up release automation".

App Store release

A release loop for iOS apps that already exist as code. It was written from shipping more than thirty App Store versions of native SwiftUI, XcodeGen and Expo apps, mostly from a Windows PC driving a Mac over SSH, and it keeps the fixes for what went wrong along the way.

For building an app from nothing, or for Google Play, use the mobile-app skill in this pack. This skill is the iOS half of its "ship" and "watch review" stages, done in depth.

Everything runs through the scripts in scripts/. They need Python 3.9+ with pip install pyjwt cryptography, and an App Store Connect API key. They do not need the asc CLI, fastlane or a Mac, except for the build itself.

ScriptDoesChanges anything?
release_config.pyPer-app config, version and build bumpsOnly local files
asc_status.pyWhere the app stands, what blocks a release, --watch for the reviewNo
mac_release.shOn the Mac or CI runner: check, archive, sign, export, uploadUploads a build in upload mode
manual_sign.pySwitches Release configs to manual signing per bundle idProject file, restored afterwards
fetch_profiles.pyDownloads provisioning profiles by nameNo
upload_ipa.pyUploads an .ipa with the Build Upload API, no Mac neededUploads a build
asc_submit.pyVersion, build, What's New, notes, purchases, submit. Dry run unless --submitYes, with --submit
asc_availability.pyWhere the app is on sale; creates a missing availability record with --applyOnly with --apply
asc_api.pyThe API client the others use; also a raw GET/POST/PATCH commandAs asked

How far each script has been exercised is stated in Status of the scripts. Read it before trusting a write path.

Rules

  1. The config decides how much to ask. .asc/release.json has autonomy:
    • submit: go from bump to "submitted for review" without stopping. Stop only for a blocker, a rejection, or anything that would cancel a submission already in review.
    • testflight: stop after the build is uploaded and processed. Submit when the user says so.
    • ask: show the dry run and wait for a yes before each upload and each submission. With no config yet, behave as ask and run the setup first.
  2. Always dry-run asc_submit.py first, even under submit. It is free, and its blockers are the whole pre-flight check.
  3. Never cancel a submission that is in review without the user's say-so, whatever the autonomy level. Cancelling throws away the place in the queue and closes the Resolution Center thread.
  4. One build number, one upload. A build number can never be reused, even after a failed upload. Bump it for every archive.
  5. Report the furthest state you verified, not the one you expect. "Uploaded" means App Store Connect lists the build as VALID. "Submitted" means the version is WAITING_FOR_REVIEW. Never promise approval or a review time.
  6. Secrets stay out of the repository and out of the chat. The config holds ids, names and paths only.
  7. When something fails, check references/gotchas.md before improvising. Most failures here have happened before and have a known cause.

Setup (once per app)

Do this the first time, or when .asc/release.json is missing. Full detail and the exact questions are in references/setup.md.

  1. From the app's repository root: python <skill>/scripts/release_config.py init. It detects the project kind (Expo, XcodeGen, plain Xcode), the bundle id, the scheme and where the version numbers live.
  2. Make sure an API key profile exists (~/.config/appstoreconnect/credentials.env) and works: python scripts/asc_api.py apps. The app must be in that list. If it is not, the key belongs to another Apple team.
  3. Fill what can be looked up: app_id from the apps list; team_id and signing.profiles from python scripts/fetch_profiles.py --list, which prints the team id, bundle id and name of every profile.
  4. Ask the user the setup questions in references/setup.md: autonomy, build hosts, how rejections are read, release type, and export compliance. Ask them once, write the answers into the config, and do not ask again on later releases.
  5. python scripts/release_config.py show must end with "Config is complete."
  6. Commit .asc/release.json.

A brand-new app that has never been on the store needs more than this. Follow references/first-release.md before the first submission.

The release loop

1. Look before touching anything

python scripts/asc_status.py APP_ID

Read the whole report. It changes what happens next:

The report saysThen
Newest version READY_FOR_SALENormal update. Continue.
A version is WAITING_FOR_REVIEW or IN_REVIEWSomething is already in flight. Either wait for it, or this is a hotfix: see Replacing a build in review.
REJECTED, METADATA_REJECTED or a submission in UNRESOLVED_ISSUESRead the rejection first: references/rejections.md. Do not resubmit unchanged.
PENDING_DEVELOPER_RELEASEAn approved version is waiting for a manual release. Ask the user: release it, or replace it.
"refusing API calls until the Account Holder accepts"Stop. Only the account holder can fix it, on the web. Nothing else will work until then.
"No availability record"Fix with asc_availability.py before anything else.

2. Version and build

python scripts/release_config.py show                       # current numbers
python scripts/release_config.py bump --patch --build auto  # 1.2.3 -> 1.2.4, build = highest anywhere + 1
  • A released version number cannot be submitted again. Any update needs a new one.
  • The default for "ship an update" with no number given is a patch bump. Use --minor for new features if the user says so.
  • --build auto reads the highest build number already on App Store Connect, so a build number is never reused.
  • A hotfix for a version still in review keeps the version and takes only a new build: bump --build auto.
  • After a project generator runs (xcodegen generate, expo prebuild), the archive can silently carry 1.0 (1). mac_release.sh refuses an archive whose numbers differ from the config's, so do not skip APP_VERSION / APP_BUILD.

3. What's New and review notes

  • Write What's New to the file named in release.whats_new. Plain sentences about what changed for the user. 4000 characters at most. Every locale the listing has needs text for an update; --whats-new-all copies it to locales that have none.
  • Review notes (release.review_notes) are capped at 4000 characters. Update them whenever a release changes what the reviewer will see: a new paywall, a changed free limit, a new login, a new permission. Stale notes that contradict the app get rejections.
  • If App Review asked a question on the last round, answer it in the notes.

Commit the bump and the text together.

4. Build and upload

Pick the host in the order build.hosts lists. Details, the SSH recipe and the CI setup are in references/build-hosts.md.

On a Mac over SSH (mac):

ssh -o BatchMode=yes -o ConnectTimeout=10 USER@MAC true          # reachable? if not, go to the next host
git push MAC_REMOTE HEAD:refs/heads/BRANCH                       # code to the Mac
ssh USER@MAC 'mkdir -p ~/.cache/app-store-release'
scp <skill>/scripts/* USER@MAC:~/.cache/app-store-release/      # the scripts, every release (overwrites the old copy)
ssh USER@MAC "$(python scripts/release_config.py env | tr '\n' ' ') \
  ASC_KEY_ID=... ASC_ISSUER_ID=... ASC_PRIVATE_KEY_PATH=... bash ~/.cache/app-store-release/mac_release.sh check"

Run check first. It reports the checkout, disk, power, certificate and profiles, and fails early instead of forty minutes in. Then run the same command with upload. Run it under nohup with output to a log file and poll the log: an SSH session that drops kills a foreground build. The last line is MAC_RELEASE_OK upload 1.2.4 (57) or MAC_RELEASE_FAILED <step>.

On GitHub Actions (github), when the Mac does not answer:

gh workflow run ios-release.yml --repo OWNER/REPO --ref BRANCH -f mode=upload
gh run watch --repo OWNER/REPO

IPA built elsewhere: mac_release.sh ipa leaves an .ipa; copy it off the Mac in one go and upload it from any machine with python scripts/upload_ipa.py App.ipa APP_ID --wait 20.

If no host is available, say so and stop. Do not sit in a retry loop against a sleeping Mac.

5. Submit

python scripts/asc_submit.py --app APP_ID --version 1.2.4 --build 57 --whats-new PATH            # dry run
python scripts/asc_submit.py --app APP_ID --version 1.2.4 --build 57 --whats-new PATH --submit   # for real

The dry run waits for nothing and changes nothing. Read every BLOCKER and NOTE line and fix them. With --submit it waits for the build to finish processing (usually 3 to 10 minutes after upload), creates or reuses the version, attaches the build, sets the text, waits for screenshots to finish processing, and submits.

The script does not read the config. Pass these flags yourself, from the release block of .asc/release.json:

ConfigFlagMeaning
release_type--release-type AFTER_APPROVAL or MANUALAFTER_APPROVAL goes live as soon as Apple approves. Without the flag an existing version keeps its setting
phased--phased7-day phased rollout. Off by default: small apps want fixes out at once
encryption_exempt--encryption-exemptAnswers export compliance when the build has no answer. Better: set ITSAppUsesNonExemptEncryption in Info.plist once
with_iaps--with-iapsSends READY_TO_SUBMIT purchases with the version. See In-app purchases
review_notes--notes FILEReplaces the App Review notes

Exit code 3 means an agreement only the Account Holder can accept. Tell the user exactly that, then run the same command again once they have.

6. Watch the review

python scripts/asc_status.py APP_ID --watch --timeout 12h --interval 10m

Run it in the background. It exits 0 when approved, 1 when rejected, 3 when nothing is in review any more (the submission was cancelled), 7 when still pending at the timeout. Do not cancel a submission because review is slow. For a genuine emergency, the pack's expedite-review skill drafts Apple's expedite request.

7. After approval

  1. python scripts/asc_status.py APP_ID: the version should be READY_FOR_SALE (or PENDING_DEVELOPER_RELEASE for a manual release, which the user then triggers).
  2. python scripts/asc_availability.py APP_ID: confirm it is actually on sale. READY_FOR_SALE with no availability record means on sale nowhere.
  3. Open the store page (https://apps.apple.com/app/idAPP_ID) and check the version number shown. The page is the truth; the iTunes lookup API can lag a day behind.
  4. Tag the commit: git tag v1.2.4-57 && git push --tags. The exact source of every shipped build should be recoverable.
  5. Tell the user: version, build, when it was submitted and approved, and anything left open.

8. If it is rejected

Follow references/rejections.md. In short: the API does not return the reviewer's message, so read it in the Resolution Center (in the browser, signed in) or have the user paste it; decide whether the answer is a reply, new metadata, or a new build; put the answer to any question into the review notes; then resubmit. Reply in the thread before cancelling anything, because cancelling removes the reply box.

Special cases

Replacing a build in review

Use when a bug is found while a version waits for review. Confirm with the user first (rule 3).

  1. release_config.py bump --build auto (same version, new build), build and upload as usual.
  2. asc_submit.py ... --replace-in-review (dry run, then --submit). It cancels the open submission, waits for the version to become editable, attaches the new build, and resubmits. If the old submission carried in-app purchases, add --with-iaps: cancelling releases them, and the script refuses to cancel without it.
  3. Apple sometimes answers 500 for several minutes after a cancel. The script retries every 3 minutes for --retry-min minutes. Let it.

In-app purchases

  • A purchase or subscription going to review for the first time has to ride in the same submission as an app version. --with-iaps adds every READY_TO_SUBMIT purchase.
  • For an app's first subscriptions the API can refuse this. The script then stops before submitting and says so. The way in is the web: open the subscription group in App Store Connect, choose "Add for Review" so it joins the version's draft submission, then run asc_submit.py again without --with-iaps.
  • Never let a version that depends on new purchases go to review without them. The reviewer cannot buy what is not in the submission, and the app is rejected.
  • After a cancelled submission, purchases fall back to READY_TO_SUBMIT and have to be added again.
  • Do not change a purchase's price while it is in review.

More than one Apple team

An API key only sees its own team's apps. Keep one profile per team (~/.config/appstoreconnect/<name>.env), set credentials_profile in the app's config, and pass --profile <name> to the scripts. If asc_api.py apps does not list the app, it is the wrong team, not a missing app.

Expo and React Native

Set project.prebuild to the command that generates ios/ (for example npm ci && npx expo prebuild --platform ios). Version and build live in app.json; bump keeps android.versionCode in step when it was already equal to the iOS build number. If prebuild adds an entitlement the App Store profile does not carry (push is the usual one), the archive fails at signing: remove the entitlement with a config plugin or regenerate the profile with the capability.

Status of the scripts

Stated plainly, so nobody trusts more than was shown.

  • Run against live App Store Connect accounts while writing this skill: asc_api.py, asc_status.py (apps that were live, in review, rejected, and never released), asc_submit.py in dry-run mode only (already in review, replace in review, already released, expired build, rejected with an open submission, update with and without an existing version, never submitted), upload_ipa.py up to its two refusal checks, fetch_profiles.py, asc_availability.py in report mode.
  • Run against copies of real projects: release_config.py (Expo app.json, XcodeGen project.yml, a plain .xcodeproj), manual_sign.py.
  • Not run in this form: every write in asc_submit.py --submit, the upload itself in upload_ipa.py, asc_availability.py --apply, and mac_release.sh as a whole (no Mac was reachable: it passed a syntax check, and its lock, keychain-list, escaping and signal-handling logic were tested on their own under bash on another system). Each is a generalised port of a script that did ship real releases with the same API calls and the same xcodebuild and security commands, and the code was reviewed by a second pass, but a port can break what the original got right. Watch the first real use of each.
  • Never run: templates/ios-release.yml.

When one of these does its first real run, fix whatever it turns up and update this section.

References

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexUnverifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall