deonmenezes/mobile-app-skill / skills/app-store-release
app-store-release
UnverifiedShip 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.
| Script | Does | Changes anything? |
|---|---|---|
release_config.py | Per-app config, version and build bumps | Only local files |
asc_status.py | Where the app stands, what blocks a release, --watch for the review | No |
mac_release.sh | On the Mac or CI runner: check, archive, sign, export, upload | Uploads a build in upload mode |
manual_sign.py | Switches Release configs to manual signing per bundle id | Project file, restored afterwards |
fetch_profiles.py | Downloads provisioning profiles by name | No |
upload_ipa.py | Uploads an .ipa with the Build Upload API, no Mac needed | Uploads a build |
asc_submit.py | Version, build, What's New, notes, purchases, submit. Dry run unless --submit | Yes, with --submit |
asc_availability.py | Where the app is on sale; creates a missing availability record with --apply | Only with --apply |
asc_api.py | The API client the others use; also a raw GET/POST/PATCH command | As asked |
How far each script has been exercised is stated in Status of the scripts. Read it before trusting a write path.
Rules
- The config decides how much to ask.
.asc/release.jsonhasautonomy: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 asaskand run the setup first.
- Always dry-run
asc_submit.pyfirst, even undersubmit. It is free, and its blockers are the whole pre-flight check. - 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.
- One build number, one upload. A build number can never be reused, even after a failed upload. Bump it for every archive.
- 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 isWAITING_FOR_REVIEW. Never promise approval or a review time. - Secrets stay out of the repository and out of the chat. The config holds ids, names and paths only.
- 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.
- 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. - 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. - Fill what can be looked up:
app_idfrom theappslist;team_idandsigning.profilesfrompython scripts/fetch_profiles.py --list, which prints the team id, bundle id and name of every profile. - 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.
python scripts/release_config.py showmust end with "Config is complete."- 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 says | Then |
|---|---|
Newest version READY_FOR_SALE | Normal update. Continue. |
A version is WAITING_FOR_REVIEW or IN_REVIEW | Something 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_ISSUES | Read the rejection first: references/rejections.md. Do not resubmit unchanged. |
PENDING_DEVELOPER_RELEASE | An 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
--minorfor new features if the user says so. --build autoreads 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.shrefuses an archive whose numbers differ from the config's, so do not skipAPP_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-allcopies 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:
| Config | Flag | Meaning |
|---|---|---|
release_type | --release-type AFTER_APPROVAL or MANUAL | AFTER_APPROVAL goes live as soon as Apple approves. Without the flag an existing version keeps its setting |
phased | --phased | 7-day phased rollout. Off by default: small apps want fixes out at once |
encryption_exempt | --encryption-exempt | Answers export compliance when the build has no answer. Better: set ITSAppUsesNonExemptEncryption in Info.plist once |
with_iaps | --with-iaps | Sends READY_TO_SUBMIT purchases with the version. See In-app purchases |
review_notes | --notes FILE | Replaces 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
python scripts/asc_status.py APP_ID: the version should beREADY_FOR_SALE(orPENDING_DEVELOPER_RELEASEfor a manual release, which the user then triggers).python scripts/asc_availability.py APP_ID: confirm it is actually on sale.READY_FOR_SALEwith no availability record means on sale nowhere.- 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. - Tag the commit:
git tag v1.2.4-57 && git push --tags. The exact source of every shipped build should be recoverable. - 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).
release_config.py bump --build auto(same version, new build), build and upload as usual.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.- Apple sometimes answers 500 for several minutes after a cancel. The script retries every 3 minutes for
--retry-minminutes. 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-iapsadds everyREADY_TO_SUBMITpurchase. - 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.pyagain 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_SUBMITand 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.pyin 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.pyup to its two refusal checks,fetch_profiles.py,asc_availability.pyin report mode. - Run against copies of real projects:
release_config.py(Expoapp.json, XcodeGenproject.yml, a plain.xcodeproj),manual_sign.py. - Not run in this form: every write in
asc_submit.py --submit, the upload itself inupload_ipa.py,asc_availability.py --apply, andmac_release.shas 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 samexcodebuildandsecuritycommands, 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
- references/setup.md: the config file, credentials, and the questions to ask once.
- references/build-hosts.md: building on a Mac over SSH, the GitHub Actions fallback, and getting code and scripts to the host.
- references/first-release.md: everything a brand-new app needs before its first submission.
- references/rejections.md: reading a rejection, replying, and resubmitting without losing the thread.
- references/gotchas.md: every failure met so far, with its cause and fix.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 468k | Updated | Claude CodeCodex | Unverified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |