Release assistant

Release Assistant

Take a product from "build is ready" to "live on the store(s)" across three ecosystems:

Store	Console	Binary	Primary automation surface
Apple App Store	App Store Connect (ASC)	.ipa	ASC REST API (near-total coverage)
Google Play	Play Console	.aab	Console UI (browser automation); Play Developer API optional
Huawei AppGallery	AppGallery Connect (AGC)	HarmonyOS: .app/.hap · Android channel: .apk/.aab	Console UI (browser automation); Connect API optional

The skill is product-agnostic: everything product-specific lives in two campaign files (below), never in this skill.

Operating model

A release is a campaign: long-lead compliance items, shared launch infrastructure, and up to three parallel per-store tracks, coordinated through one state document. Work splits into what the agent can do (API calls, browser automation, builds, file generation, verification) and what only the owner can do (payments, identity verification, SMS codes, CAPTCHA, legal judgment calls, irreversible actions). Batch owner actions; never block on them silently.

Phase 0 — Campaign setup

1. Scope: product, target stores, target regions (China mainland? overseas?), first release vs update vs rejection recovery.
2. Platform feasibility gate — before promising a store, verify the stack can build for it:
   • HarmonyOS NEXT requires an ArkTS/ArkUI (or supported hybrid-shell) build. Flutter/React Native have no official HarmonyOS NEXT target — if the product can't build it, AGC options are the Android channel (standard APK; see references/appgallery.md §10) or dropping AGC. Surface this to the owner as a decision, with lead-time impact.
   • Record the verdict per store in the release profile platforms:/stores: fields.
3. Campaign files:
   • Release profile (per product, long-lived): copy assets/release-profile.template.yaml to docs/release/release-profile.yaml in the product repo; fill by scanning the repo (bundle IDs, build system, version files, existing certs config) + interviewing the user for the rest.
   • Campaign state doc (per release): copy assets/release-state.template.md to docs/release/<YYYY-MM-DD>-store-submission-status.md. This is the single source of truth (SoT) shared by every session on the campaign.
4. Update campaigns / resuming: locate the release profile and the most recent archived state doc first (convention: same docs/release/ directory, dated filenames). Carry forward: consumed Apple build numbers, store console coordinates, demo-account status, rejection lessons, unfinished owner TODOs. Link the old doc from the new one's Previous campaign field. Store forms persist between releases — only re-touch what reality changed (privacy forms only if the disclosure matrix changed).

State-doc discipline (non-negotiable):

• Read the state doc before acting; write back after every milestone with a date-time stamp; commit to git after each write-back so conflicts surface as merges, not silent overwrites.
• Ownership: each store session owns its own track section and its own row in the overview table; shared sections (§1 infra, §5 compliance, §6 owner TODO, §7 rejections log, §8 while-waiting queue) take appends from anyone — prefix entries with your session tag (e.g. [ios-0727]). Never rewrite another track's content.
• Record console coordinates as you learn them: app IDs, internal IDs, submission IDs, consumed build numbers, artifact paths. A future session must be able to resume from the doc alone.
• Never write secrets, passwords, API keys, or demo-account credentials into the state doc or any repo file. Record where a secret lives (keychain item name, env var name, console form), not the value.

Phase 1 — Critical path first

Before touching any listing, enumerate long-lead items and start them immediately. Typical lead times (details and exact procedures in references/china-compliance.md; verify current figures when they matter):

Item	Lead time	Applies when
ICP App 备案 (MIIT app filing)	~8–23 working days total	Distributing in China mainland on any store. One filing covers all platforms of the same app
Google Play closed-testing gate: 12 opted-in testers × 14 continuous days	≥ 14 days + recruiting	Personal Play accounts created after 2023-11-13 (orgs and older accounts exempt)
Software copyright 软著 (CPCC official channel)	receipt ~3 wd; certificate 50–75 wd	China stores. AGC's own docs mark it required for China-mainland phone apps; domestic Android stores require it. Start day one
Developer accounts + identity verification (Apple, Play, AGC 实名认证)	hours–days (enterprise D-U-N-S: 1–2 weeks)	Always. AGC personal 实名 suffices to publish; enterprise 实名 needed for paid/commercial categories
EU DSA trader declaration	minutes, but a privacy decision	Selling into the EU on Apple/Google: traders must declare status; an individual trader's address + phone become public on EU store pages. Owner decides: declare, or exclude EU from availability
Review demo account with seeded data on production	hours	All stores, if the app has auth
AI-generated-content declaration evidence	hours — or a hard stop	China distribution with AI features: needs the upstream model's Chinese filing numbers. If the real upstream (e.g. OpenAI) has none, the declaration cannot be truthfully made — escalate to owner (see references/china-compliance.md §3)

Phase 2 — Shared launch infrastructure

Read references/shared-launch-infra.md, then ensure before any store form is filled:

1. Deep-link / app-link domain serves the well-known files with correct body and content-type. Verify with scripts/check-deeplink-live.mjs — body-level checks catch the classic "content-type says JSON but body is index.html" SPA-fallback failure. Verification is two-pass: initial pass early (skip identifiers you don't have yet — the AGC App ID and Play App Signing SHA-256 only exist after Phase 3 app creation/enrollment; use --skip), final full pass before each store's submission.
2. Privacy policy and terms URLs return HTTP 200, publicly, and their content covers what the app actually collects.
3. Data disclosure matrix: one document listing every data type collected, purpose, sharing, encryption, deletion path. All three stores' privacy forms (ASC App Privacy, Play Data safety, AGC 隐私标签) are projections of this matrix — never invented per-form.
4. Review demo account: production account, least privilege, seeded demo data, and login proven both via a production API call and through the real login UI on a clean device/session (API proof misses CAPTCHA, 2FA, device risk-control, region gates). If login is SMS-OTP-only or third-party-OAuth-only, reviewers cannot use it — provide a password-type review account or a fixed test OTP.
5. Screenshots per store spec, produced without shipping demo seed in the submitted binary.

Phase 3 — Per-store execution

Read the platform reference before working that store:

• references/app-store.md — ASC API automation map, build/upload, beta-toolchain traps (ITMS-90534/90111), TestFlight, encryption compliance, review setup.
• references/google-play.md — Play App Signing, testing tracks and the 12×14 gate, Data safety, IARC, App access, pre-launch report.
• references/appgallery.md — AGC console flow, HarmonyOS ECC P-256 signing, Android channel, per-device-type screenshots, 隐私标签, AI declaration, App Linking.

Automation policy, in order of preference:

1. Official API (ASC covers most of Apple's flow — scripts/asc-client.mjs).
2. Browser automation on consoles (AGC and Play forms). Console login itself usually needs owner SMS/CAPTCHA — the owner logs in and hands over the authenticated session; treat the browser profile as a live credential (record its location in the state doc, destroy it at campaign end). Snapshot form state after saves as evidence, except forms showing credentials (review-account forms): never screenshot visible passwords; mask or crop first.
3. Owner action — payments, identity verification, SMS/CAPTCHA, legal sign-offs, irreversible operations. Maintain one running owner-TODO table in the state doc with exact clicks/values — but credentials only by reference (keychain:<item>), never inline.

If browser automation is unavailable, downgrade that store's console work to owner TODOs with exact field-by-field values — that is a legitimate mode, not a failure.

Store listing copy: start from assets/metadata.template.json, validate with scripts/check-metadata-limits.mjs <file> --require before each store's submission, alongside the store's own pre-submit checklist from its reference.

Phase 4 — Submit, wait, react

• Review-period freeze: while any store review is pending, freeze risky production-backend changes — reviewers log in at unpredictable times (full rules: references/shared-launch-infra.md §6).
• Waiting time is work time: process the while-waiting queue (website store badges behind switches, next-version fixes, compliance items still in flight).
• On rejection: references/rejection-recipes.md — map the code/text to a recipe, fix, log cause + fix in the state doc.

Phase 5 — After approval

Read references/post-approval.md: store URLs live, deep-link verification on device, unfreeze + deferred server work, credential rotation, next-version bump ritual, campaign retrospective.

Non-negotiable rules

Evidence before claims

• Never mark a step done without evidence: an API response, an HTTP status + body check, a (credential-free) console screenshot, a command output. "Filled" ≠ "verified".
• Test logins, URLs, and endpoints on production before writing them into review forms.
• Store policies drift. Facts in this skill were verified 2026-07; reconfirm load-bearing numbers (fees, tester counts, size tables) against the official console/doc before relying on them.

Version discipline

• One version source of truth; bump it first, then fan out to platform manifests. Never hand-edit one platform ad hoc.
• Apple build numbers are consumed forever once uploaded for a version string — including by rejected builds. Track consumed numbers in the state doc and release profile; next build strictly higher.

Secrets

• Signing keys, API keys (.p8/.p12/keystores), and passwords live outside the repo (OS keychain / secrets manager / gitignored env file). Repo and state doc hold only references. Never create private_keys/ or copy key files inside a git repo, even temporarily.
• Demo-account credentials: store consoles + the owner's password manager / OS keychain only. Sessions that need the value read it from the agreed channel recorded in the release profile (review.credentials_channel), e.g. security find-generic-password -s <item> -w.
• Certificate fingerprints and public keys are not secrets (ICP filings need them); private keys are.

Destructive-action gates (owner approval required, recorded in the state doc)

• Revoking certificates or profiles (enumerate what else uses them first — team-level blast radius).
• Any DELETE, or writes to certificates/profiles resources, via the ASC API.
• The ITMS-90111 IPA patch (see references/app-store.md §4 — it rewrites a value Apple's validation reads; preferred fix is building on release macOS).
• Anything the owner cannot undo: account-level settings, pulling a live app, filing legal declarations.

Truthful forms

• Privacy forms derive from the disclosure matrix; app behavior changes → matrix first → re-fan-out.
• Filing numbers (ICP, 算法备案, 软著) must be your own and real — never borrow another provider's numbers even if publicly listed, never fabricate. If a truthful declaration is impossible, stop and escalate; that is a product decision, not a form-filling problem.
• Reference-doc answer templates ("typical shape") are shapes, not answers: derive every form answer from the matrix/codebase and verify claims (e.g. confirm the WebView really loads only bundled content before asserting it to a reviewer).
• Never overstate in listing copy; screenshots show only shipped features with de-identified demo data.

Scripts

All zero-dependency (Node ≥ 18; the IPA patcher needs macOS + Xcode CLTs). Each supports --help.

Script	Purpose	Example
scripts/asc-client.mjs	ASC API JWT + authenticated requests	node scripts/asc-client.mjs GET '/v1/apps?filter[bundleId]=com.example.app'
scripts/check-deeplink-live.mjs	Body-level verification of the three well-known files	node scripts/check-deeplink-live.mjs link.example.com --android-package com.example.app --ios-appid TEAMID.com.example.app --skip harmony
scripts/check-metadata-limits.mjs	Per-store character limits on listing copy (--require = fail on empty/unknown fields; use for pre-submit gates)	node scripts/check-metadata-limits.mjs metadata.json --require
scripts/patch-ipa-buildmachine.sh	ITMS-90111 fallback fix (owner-gated): rewrite BuildMachineOSBuild in an exported IPA, re-sign, re-zip	scripts/patch-ipa-buildmachine.sh app.ipa --sign-identity "Apple Distribution: Name (TEAMID)" --build-machine-os <release-build>

Reference index

File	Read when
references/app-store.md	Working the Apple track
references/google-play.md	Working the Play track
references/appgallery.md	Working the AGC track (HarmonyOS or Android channel)
references/china-compliance.md	Any China-mainland distribution: ICP App 备案, 软著, AI declaration, 公安备案, trademark
references/shared-launch-infra.md	Before filling any store form: deep links, privacy pages, demo account, screenshots, freeze rules
references/rejection-recipes.md	A store rejected or flagged the submission
references/post-approval.md	A store approved; planning the next version or resuming for an update