# App Store Release Runbook — Google Play & Apple App Store

**Owner:** Cold Bore Ballistics LLC
**Scope:** Pre-release (beta) and production release of mobile apps to the Google Play Store and the Apple App Store. Currently applies to ScopeDOPE (Android now; iOS at v1.0 launch).
**Status:** Active
**Reader:** Assume you have never opened Google Play Console or Apple App Store Connect before. This runbook does not assume prior experience with either platform.

---

## What this runbook covers and who it is for

This is the **operational how-to** for getting a built app from "I have a signed build" to "real testers have it" (pre-release) and then to "it is live in the store" (production). It is for the person performing the release.

This runbook owns **store-side procedures only**. It does **not** own:

- **What to verify before releasing** — that is the Release Checklist in `ScopeDOPE_SDLC.md` (and the mirror in `CLAUDE.md`). This runbook is invoked *by* those checklist items, not instead of them.
- **How to build the signed artifacts** (`.aab` for Android, `.ipa`/archive for iOS) — that is build tooling, documented with the build process.

Where a checklist item says "Google Play Console internal test track upload and smoke test complete" or "Apple TestFlight build uploaded and smoke tested," **this document is the procedure behind that item.**

---

## Key terms

| Term | Platform | Meaning |
|---|---|---|
| **`.aab`** | Android | Android App Bundle — the signed artifact uploaded to Play. Google generates per-device `.apk`s from it. |
| **Archive / build** | iOS | The compiled, signed app uploaded to App Store Connect from Xcode. |
| **Testing track** | Google Play | A distribution lane (Internal → Closed → Open → Production). The *same* build is promoted up the lanes. |
| **TestFlight** | Apple | Apple's separate beta-distribution app. Testers install betas through TestFlight, not the App Store. |
| **Beta App Review** | Apple | A lighter review TestFlight builds undergo before *external* testers can use them. Internal testers do not trigger it. |
| **App Review** | Apple | The full review a build undergoes before it can be released to the App Store. |
| **Staged / phased rollout** | Both | Releasing to a growing percentage of production users rather than 100% at once. |

---

## The mental model (read this once)

The two stores work differently. Hold this distinction:

- **Google Play** = **one build, promoted up a ladder of tracks.** You upload the `.aab` once to Internal testing, smoke-test it, then promote that *same* build to Closed → Open → Production. Testers install through the **normal Play Store app**.
- **Apple** = **two separate destinations.** Betas live in **TestFlight** (a separate app testers install from). The **App Store** is a different, full-review destination. A build goes to TestFlight first (internal testers instantly, external testers after a light Beta App Review), then is submitted separately for full App Store Review.

---

## Part A — Google Play (Android)

### A.0 Prerequisites

Before step 1 you must have:

- A signed Android App Bundle (`.aab`) for the release version.
- Access to **Google Play Console** (`https://play.google.com/console`) for the Cold Bore Ballistics LLC developer account.
- The app already created in Play Console (one-time setup, not covered here).

### A.1 The testing tracks

Play exposes four lanes. You upload to the lowest and promote upward.

| Track | Audience | How testers are added | Store review |
|---|---|---|---|
| **Internal testing** | Up to **100** testers | Email address list | Minimal — typically available within minutes |
| **Closed testing** | Up to **2,000 testers per list**; up to **50 lists per track**, 200 lists total | Email lists, Google Groups, or org-managed | Full review |
| **Open testing** | Unlimited (or a set minimum) | Public opt-in link; discoverable | Full review |
| **Production** | Everyone | — | Full review |

### A.2 Procedure — pre-release to Internal testing

This is the procedure behind the checklist item *"Google Play Console internal test track upload and smoke test complete."*

1. Sign in to **Google Play Console** → select the app.
2. In the left navigation, expand **Test and release** → **Testing** → **Internal testing**.
3. On the **Testers** tab, create or select an email list of internal testers (the founder's tester account at minimum). Save.
4. Switch to the **Releases** tab → **Create new release**.
5. Under **App bundles**, upload the signed `.aab`.
6. Enter **Release notes** (what testers should look for).
7. Click **Next** → review → **Save and publish** (or **Start rollout to Internal testing**).
8. Wait for the build to process (usually minutes).
9. On the **Testers** tab, copy the **opt-in URL** (the "Copy link" control). Open it on the test device, accept the invitation, then install ScopeDOPE from the Play Store on that device.
10. **Smoke test** on the device: full UI walkthrough, BLE pairing, and the print pipeline (per the Release Checklist's manual-test items).

**Verification:** The app installs from the Play Store on the test device via the opt-in link, launches, and the smoke test passes. If it does not install, confirm the device's Google account is on the tester list.

### A.3 Procedure — promote toward production

1. In **Production** (or the next track up), choose **Create new release** → **Add from library** and select the *same* build already tested. Do **not** re-upload a different artifact.
2. Enter production release notes.
3. **Set a staged rollout percentage** — start at **10%** (this is the checklist's post-release ramp).
4. **Save and publish.** The build enters full **App Review**; it goes live to the rollout percentage once approved.
5. After monitoring (see Release Checklist post-release items), increase the percentage: **10% → 50% → 100%**.

**Verification:** The release shows as "Available on Google Play" at the intended rollout percentage, and crash/rating monitoring is in place for the post-launch window.

### A.4 Account-type note (affects production eligibility)

Google requires **personal** developer accounts created after **2023-11-13** to run a closed test with **≥ 12 testers opted in for ≥ 14 continuous days** before they may apply for production access. **Organization accounts are exempt from this requirement.** If the ScopeDOPE Play account is registered to **Cold Bore Ballistics LLC** as an organization, this gate does not apply. **Confirm the account type before assuming the fast path** — see "Open item" at the end.

---

## Part B — Apple App Store (iOS)

### B.0 Prerequisites

Before step 1 you must have:

- A paid **Apple Developer Program** membership (under the LLC).
- Access to **App Store Connect** (`https://appstoreconnect.apple.com`).
- An app record created in App Store Connect (one-time setup, not covered here).
- Xcode with the project, able to archive and upload.

### B.1 The two TestFlight tiers

| Tier | Audience | How testers are added | Beta App Review |
|---|---|---|---|
| **Internal testing** | Up to **100** App Store Connect team members | Added by Apple ID / team role | **No review** — available within minutes |
| **External testing** | Up to **10,000** testers | Email invite or public TestFlight link | **Yes** — first build added to a group goes to Beta App Review; later builds may not |

Builds remain available on TestFlight for **up to 90 days**, then expire.

### B.2 Procedure — pre-release to TestFlight (internal)

This is the procedure behind the checklist item *"Apple TestFlight build uploaded and smoke tested."*

1. In **Xcode**, select **Product → Archive** to build the signed archive.
2. In the **Organizer** window that opens, select the archive → **Distribute App** → **App Store Connect** → **Upload**. (Transporter or `xcodebuild` are alternatives.)
3. Sign in to **App Store Connect** → select the app → **TestFlight** tab.
4. Wait for the uploaded build to finish **Processing** (a few minutes; status shown on the TestFlight tab).
5. Under **Internal Testing**, add an internal group (or use the default) and ensure the founder's Apple ID is a member. Internal testers receive the build with **no Beta App Review**.
6. On the test device, install the **TestFlight** app from the App Store, sign in with the tester Apple ID, and install ScopeDOPE from within TestFlight.
7. **Smoke test** on the device: full UI walkthrough, BLE pairing, print pipeline.

**Verification:** The build appears in TestFlight on the device, installs, launches, and the smoke test passes.

### B.3 Procedure — external TestFlight (optional, wider beta)

1. On the **TestFlight** tab, create an **External** group.
2. Add the **first build** to the group — this triggers **Beta App Review** (typically about a day).
3. Once approved, invite external testers by **email** or share the group's **public TestFlight link**.

**Verification:** The external group shows the build as approved, and an invited external tester can install it via TestFlight.

### B.4 Procedure — submit to the App Store (production)

1. In App Store Connect, open the app's **Distribution / App Store** section and create/prepare the version (screenshots, description, what's-new, privacy details as required).
2. Select the **build** (the same one tested in TestFlight).
3. Submit for **App Review** (full review — longer than Beta App Review).
4. Choose the release method: **manual**, **automatic on approval**, or **phased release** (Apple's 7-day automatic percentage ramp).

**Verification:** The version status reaches **Ready for Sale** (or is releasing via phased rollout), and post-launch monitoring is in place.

---

## Mapping to the Release Checklist

The authoritative Release Checklist lives in `ScopeDOPE_SDLC.md` (mirrored in `CLAUDE.md`). This runbook does not restate it. The store-side items map as follows:

| Checklist item | Procedure here |
|---|---|
| Google Play Console internal test track upload and smoke test | §A.2 |
| Apple TestFlight build uploaded and smoke tested | §B.2 |
| Google Play staged rollout (10% → 50% → 100%) | §A.3 |
| Apple App Store submission complete | §B.4 |

---

## Limits and rules are subject to change

Apple and Google revise tester limits, review timing, and account rules periodically. The figures here were verified against the official **Apple App Store Connect Help** and **Google Play Console Help** on **2026-06-12**. Before relying on an exact number for a release, re-verify against the current official docs.

---

## Open item — account enrollment (acquisition-relevant)

This runbook's fast paths (§A.4 organization exemption; §B prerequisites) assume the **Google Play** and **Apple Developer** accounts are enrolled under **Cold Bore Ballistics LLC** as an organization, not a personal account. This has **not been confirmed in this document.** Confirm and record the enrollment type for each store in `App_Store_Accounts` (`OneDrive/CBB_Corporate/02_-_General/App_Store_Accounts/`). Organization enrollment is also the correct state for acquisition — store assets and IP should sit with the company, not an individual.
