Publish App Store Version

Publish KeeForge App Store Version

Scope and authorization

Use the documented App Store Connect REST API at https://api.appstoreconnect.apple.com with API-key authentication. No signed-in browser, session cookies, or private website APIs are required. If an operation is unavailable through the public API or the key lacks permission, report the specific blocker. Do not silently switch to browser automation or broaden key access.

Operate only on the requested platforms and fields. Prepare localization, attachment, and review-draft writes within the authorized scope. Show the English release-note draft before saving public copy unless already approved. Retain the version-creation and final-submission confirmation boundaries below.

Staging ends before final submission. PATCH /v1/reviewSubmissions/{id} with submitted: true sends the contents to Apple; it is not a validation or staging request. Obtain a separate explicit action-time confirmation immediately before each platform's final submission, naming its exact version and build. Approval for iOS does not imply approval for macOS. A request to prepare everything before submission authorizes neither submission nor production release. Never use the legacy appStoreVersionSubmissions POST as a way to stage a draft.

Beta App Review, external TestFlight distribution, production submission, production release, and legal declarations are separate actions. Perform them only within the user's explicit scope. Do not add a platform, change purchase configuration, or change availability as a side effect of publishing an existing platform.

Credentials stay local

Read applicable private local guidance for credential discovery. Otherwise use configured environment variables or a user-specified private environment file:

• APP_STORE_CONNECT_KEY_ID
• APP_STORE_CONNECT_ISSUER_ID for a team API key
• APP_STORE_CONNECT_KEY_PATH for the private .p8 key

The public skill must contain no actual key or issuer IDs, credential filenames, personal filesystem paths, reviewer contact details, or tokens. Keep machine-specific discovery paths in private, Git-excluded local guidance. Do not copy the credentials into this skill, scratch artifacts, release manifests, issues, commits, or terminal output. Parse an environment file as data; do not execute its contents. Resolve configured home-relative paths in process.

Generate a short-lived ES256 JWT using an established library such as PyJWT with cryptography. For a team key use iss, iat, exp, and aud: appstoreconnect-v1; header fields are kid, typ: JWT, and alg: ES256. A two-minute lifetime suits a preflight; keep other tokens at or below 20 minutes and renew during longer work. Individual keys use sub: user instead of iss; confirm key type rather than guessing from a missing issuer.

Keep the key and JWT in memory. Send the bearer token only to the API origin above. Do not put it in process arguments, shell traces, HTTP debug output, or a printed request object. Disable automatic redirects for authenticated requests. Upload URLs have their own authorization and must not receive the ASC bearer token.

Start with a read-only app lookup to verify authentication and app identity. A successful GET proves read access only, not permission to submit or release. For 401, check token expiry, clock, and configured key type; for 403, report the missing permission without changing roles.

See API operations for endpoints, JSON:API request shapes, upload handling, and current Apple documentation. Verify the current documented schema before using a field not covered there.

Release inputs and platform identity

KeeForge has one app record with separate IOS and MAC_OS versions, builds, localizations, screenshots, and review submissions. Resolve the app from the handoff or the repository's main bundle identifier, then confirm its identity. Do not select an app by display name alone.

The prepare-release and respin-release skills prepare the candidate; after soak, ship-release hands off the accepted release manifest. Require that handoff at scratch/release-manifests/{version}-b{repoBuild}.json. Match the marketing version, repo build, RC tag/SHA, iosTestFlightBuild, macTestFlightBuild, and platform build IDs. Both builds must come from the accepted RC; directCFBundleVersion must equal repoBuild. Verify the recorded external TestFlight soak and direct-channel evidence. Internal-only testing and Xcode Cloud upload success do not establish an accepted external soak.

The direct-download Mac artifact is outside this skill: verify its handoff evidence but never upload, notarize, rebuild, or release it here. Select the existing accepted App Store builds; never substitute the newest build, trigger CI, bump versions, or make an archive. If a required manifest mapping or build is missing, stop and report it. An existing upload may still be processing; bounded polling is allowed, but do not wait for an unrequested new build.

For a narrowly requested listing correction or read-only investigation, inspect the specified record without requiring a release manifest. That scope does not authorize changing its build, staging a different candidate, or submitting it.

Other inputs:

• Read only the requested version's CHANGELOG.md section, never Unreleased.
• Preserve existing reviewer notes and contact details unless incorrect. The disposable reviewer fixture is test.kdbx.zip, with password testpassword123; resolve its local source from private guidance or user input. Never substitute a personal database.
• For Mac listing/reviewer copy, read mac-listing-metadata.md. It is a historical saved-copy reference, not live submission or release authorization. Update it after an authorized Mac copy change with redacted readback evidence only.
• Enumerate each version's actual localizations; the App Store list can differ from the app's shipped languages. Do not assume seven locales or add a locale just because the app supports it.

Workflow

1. Inspect each platform

Read the requested version, its attached build, localizations, reviewer details/attachments, screenshot sets, release settings, availability, and existing review submissions/items. Follow pagination, including nested relationship lists. Record only the non-secret IDs and state needed for the task; summarize reviewer contact completeness without printing personal contact values.

Match the build's preReleaseVersion.version and preReleaseVersion.platform as well as its ID and build.version (the build number). API processingState: VALID means processing succeeded; it is distinct from an asset's COMPLETE state. Reject failed/invalid builds and buildAudienceType: INTERNAL_ONLY for production. Inspect beta eligibility and the accepted soak evidence rather than interpreting processing success as test distribution or approval.

If a version is already submitted, in review, or released, report its actual state and use only operations valid for the requested correction. Do not cancel, withdraw, recreate, or resubmit it to force it through the preparation path.

2. Create or reuse the exact version and attach its build

Reuse the matching platform/version record. If absent, confirm creation immediately before POSTing an appStoreVersions resource related to the app, with the exact platform, versionString, and intended releaseType. Coordinate KeeForge releases with MANUAL unless the owner explicitly chooses otherwise. Check for an existing record again after an ambiguous POST outcome.

PATCH the version's build relationship with the exact manifest build ID. GET that relationship and build afterward and recheck the full platform/version/build mapping. If Apple rejects the build, report the error instead of choosing another candidate.