gowalk-cicd 1.0.13 → 1.0.15

package/README.md

@@ -66,6 +66,36 @@ workflow reads these files from the checkout, so they must be available to
 GitHub Actions (this package's zero-config convention is to track them only in
 a private repository).
 
+### Choosing which stores a repo ships to
+
+`deploy.yml` runs iOS and Android in parallel. Set the repository variable
+`DEPLOY_PLATFORMS` when one of them is intentionally out of scope, so an
+unrelated failure on the platform you do not care about cannot block the
+release you do:
+
+| `DEPLOY_PLATFORMS` | Result |
+|---|---|
+| unset / `both` | iOS + Android (default) |
+| `android` | Android only — the iOS job is skipped |
+| `ios` | iOS only — the Android job is skipped |
+
+```bash
+gh variable set DEPLOY_PLATFORMS --body android
+```
+
+### Track, status and staged rollout
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `GOOGLE_PLAY_TRACK` | `internal` | `internal`, `alpha`, `beta`, `production`, or a custom track name |
+| `GOOGLE_PLAY_STATUS` | `completed` | `completed` (full rollout) or `inProgress` (staged) |
+| `GOOGLE_PLAY_USER_FRACTION` | `0.2` | Audience share, **only** read when the status is `inProgress` |
+
+Play rejects an `inProgress` release that does not declare its audience share,
+and rejects a `completed` one that does. The workflow sends `userFraction` only
+in the mode that accepts it, so setting the fraction while leaving the status at
+`completed` is harmless rather than a failed upload.
+
 Google Play requires the first AAB to be uploaded through Play Console. The
 first CI run still succeeds and retains the signed AAB as an
 `android-<package>-<versionCode>` workflow artifact. Upload that artifact once
@@ -175,6 +205,29 @@ committed back. If the module computes its `versionCode` instead of declaring a
 literal, the action emits a `::warning::` and leaves the project's own value
 alone.
 
+### Gradle wrapper floor (Flutter apps)
+
+The Flutter Gradle plugin refuses to apply to a project whose wrapper is older
+than the SDK's floor:
+
+```
+Your project's Gradle version (8.11.1) is lower than Flutter's minimum
+supported version of 8.14.0.
+```
+
+CI installs the current `stable` Flutter, so that floor rises on Flutter's
+release cadence rather than the app's — every app in a fleet breaks on the same
+day, long after the last commit that could have anticipated it. Before building,
+the action reads the floor out of the runner's Flutter SDK and, when the
+project's `gradle-wrapper.properties` is below it, rewrites `distributionUrl`
+**in the checkout** with a `::warning::`. Same policy as the versionCode
+rewrite: the edit is never committed back, so the project keeps whatever
+version its authors chose. Commit the bump yourself to silence the warning.
+
+(The rewritten name is verified against `services.gradle.org` because Gradle's
+own naming is inconsistent across majors — `gradle-8.14-all.zip` but
+`gradle-9.0.0-all.zip`.)
+
 ### iOS delivery
 
 The iOS composite action runs on `macos-15` and:

package/action/.daemux-version

@@ -1 +1 @@
-1.0.13
+1.0.15

package/action/scripts/pbxproj_editor.py

@@ -72,20 +72,49 @@ def _bundle_id_from_configs(objects: dict, config_ids: list[str]) -> str:
     return ""
 
 
-def _entitlements_from_configs(objects: dict, config_ids: list[str]) -> str:
+def _expand_entitlements_refs(value: str, target_name: str) -> str:
+    """Expand the build-setting references we can resolve without xcodebuild.
+
+    ``$(TARGET_NAME)`` is the idiom every xcodegen target template uses for a
+    per-target entitlements path, and ``$(SRCROOT)``/``$(PROJECT_DIR)`` both
+    name the directory the path is already relative to. Those three are
+    unambiguous from the pbxproj alone; anything else is left in place so the
+    caller can reject the value.
+    """
+    for reference in (f"$(TARGET_NAME)", "${TARGET_NAME}"):
+        value = value.replace(reference, target_name)
+    for name in ("SRCROOT", "PROJECT_DIR"):
+        value = value.replace(f"$({name})/", "").replace(f"${{{name}}}/", "")
+    return value
+
+
+def _entitlements_from_configs(
+    objects: dict, config_ids: list[str], target_name: str = "", base: Path | None = None
+) -> str:
     """First CODE_SIGN_ENTITLEMENTS path across the given configs.
 
     Needed to reconcile the App ID's capabilities with what the app declares —
-    a profile only carries capabilities enabled on its App ID. Build-setting
-    references are skipped rather than half-expanded; a missed entitlements
-    file costs a clearer error, a wrong one costs a wrong App ID edit.
+    a profile only carries capabilities enabled on its App ID.
+
+    A literal path is returned as-is (the caller warns when it does not exist).
+    A path built from build settings is expanded only for the references we can
+    resolve exactly, and then only accepted when the resulting file is really
+    there — a missed entitlements file costs a clearer error, a wrong one costs
+    a wrong App ID edit.
     """
     for cid in config_ids:
         cfg = objects.get(cid) or {}
         settings = cfg.get("buildSettings") or {}
         value = (settings.get("CODE_SIGN_ENTITLEMENTS") or "").strip().strip('"')
-        if value and "$(" not in value and "${" not in value:
+        if not value:
+            continue
+        if "$(" not in value and "${" not in value:
             return value
+        expanded = _expand_entitlements_refs(value, target_name)
+        if "$(" in expanded or "${" in expanded:
+            continue
+        if base is None or (base / expanded).is_file():
+            return expanded
     return ""
 
 
@@ -102,6 +131,7 @@ def discover_signable_targets(project_path: str) -> list[dict]:
     """
     pbx = _load_pbxproj(project_path)
     objects = pbx["objects"]
+    base = Path(project_path).parent
     targets: list[dict] = []
     for obj in objects.values():
         if obj.get("isa") != "PBXNativeTarget":
@@ -120,7 +150,9 @@ def discover_signable_targets(project_path: str) -> list[dict]:
                 "name": name,
                 "bundle_id": bundle_id,
                 "config_ids": config_ids,
-                "entitlements": _entitlements_from_configs(objects, config_ids),
+                "entitlements": _entitlements_from_configs(
+                    objects, config_ids, target_name=name, base=base
+                ),
             }
         )
     if not targets:

package/action/scripts/test_pbxproj_editor.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Entitlements-path resolution in pbxproj_editor."""
+
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from pbxproj_editor import _entitlements_from_configs, _expand_entitlements_refs
+
+
+def _objects(value):
+    return {"cfg": {"buildSettings": {"CODE_SIGN_ENTITLEMENTS": value}}}
+
+
+class ExpandEntitlementsRefsTest(unittest.TestCase):
+    def test_expands_target_name_both_spellings(self):
+        self.assertEqual(
+            _expand_entitlements_refs("$(TARGET_NAME)/$(TARGET_NAME).entitlements", "Blocker"),
+            "Blocker/Blocker.entitlements",
+        )
+        self.assertEqual(
+            _expand_entitlements_refs("${TARGET_NAME}/App.entitlements", "Blocker"),
+            "Blocker/App.entitlements",
+        )
+
+    def test_srcroot_prefix_drops_out(self):
+        self.assertEqual(
+            _expand_entitlements_refs("$(SRCROOT)/App/App.entitlements", "App"),
+            "App/App.entitlements",
+        )
+
+    def test_unknown_reference_is_left_alone(self):
+        self.assertIn("$(CONFIGURATION)", _expand_entitlements_refs(
+            "$(CONFIGURATION)/App.entitlements", "App"))
+
+
+class EntitlementsFromConfigsTest(unittest.TestCase):
+    def test_literal_path_is_returned_without_touching_disk(self):
+        self.assertEqual(
+            _entitlements_from_configs(_objects("App/App.entitlements"), ["cfg"],
+                                       target_name="App", base=Path("/nonexistent")),
+            "App/App.entitlements",
+        )
+
+    def test_target_name_reference_resolves_when_the_file_exists(self):
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "Blocker").mkdir()
+            (root / "Blocker" / "Blocker.entitlements").write_text("<plist/>")
+            self.assertEqual(
+                _entitlements_from_configs(
+                    _objects("$(TARGET_NAME)/$(TARGET_NAME).entitlements"), ["cfg"],
+                    target_name="Blocker", base=root),
+                "Blocker/Blocker.entitlements",
+            )
+
+    def test_expanded_path_that_does_not_exist_is_rejected(self):
+        with TemporaryDirectory() as tmp:
+            self.assertEqual(
+                _entitlements_from_configs(
+                    _objects("$(TARGET_NAME)/$(TARGET_NAME).entitlements"), ["cfg"],
+                    target_name="Ghost", base=Path(tmp)),
+                "",
+            )
+
+    def test_unresolvable_reference_is_skipped(self):
+        self.assertEqual(
+            _entitlements_from_configs(
+                _objects("$(CONFIGURATION)/App.entitlements"), ["cfg"],
+                target_name="App", base=Path("/tmp")),
+            "",
+        )
+
+    def test_missing_setting_yields_empty(self):
+        self.assertEqual(
+            _entitlements_from_configs({"cfg": {"buildSettings": {}}}, ["cfg"]), "")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/android-action/.daemux-version

@@ -1 +1 @@
-1.0.13
+1.0.15

package/android-action/scripts/gradle_wrapper.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""Raise a Flutter app's Gradle wrapper to the version its Flutter SDK requires.
+
+The Flutter Gradle plugin refuses to apply when the project's wrapper is older
+than the SDK's floor:
+
+    Your project's Gradle version (8.11.1) is lower than Flutter's minimum
+    supported version of 8.14.0.
+
+CI installs the current `stable` Flutter, so that floor rises on Flutter's
+release cadence, not the app's. Every app in a fleet then breaks on the same
+day — long after the last commit that could have anticipated it.
+
+This raises the wrapper inside the CI checkout, the same way the action already
+rewrites versionCode there. The edit is never committed back; the project keeps
+whatever version its authors chose, and the build stops depending on the
+project having been touched since the last Flutter release.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# `stable` moves the floor over time, so read it from the SDK rather than
+# hardcoding a number this file would have to chase.
+_CHECKER = Path("packages/flutter_tools/gradle/src/main/kotlin/DependencyVersionChecker.kt")
+_ERROR_VERSION = re.compile(r"errorGradleVersion\s*:\s*Version\s*=\s*Version\((\d+),\s*(\d+),\s*(\d+)\)")
+_DISTRIBUTION = re.compile(r"^(distributionUrl=.*gradle-)([0-9]+(?:\.[0-9]+)*)(-(?:all|bin)\.zip)$", re.M)
+
+Version = tuple[int, ...]
+
+
+def parse_version(text: str) -> Version | None:
+    if not re.fullmatch(r"[0-9]+(\.[0-9]+)*", text or ""):
+        return None
+    return tuple(int(part) for part in text.split("."))
+
+
+def _render(version: Version) -> str:
+    return ".".join(str(part) for part in version)
+
+
+def _stripped(version: Version) -> str:
+    parts = list(version)
+    while len(parts) > 2 and parts[-1] == 0:
+        parts.pop()
+    return _render(tuple(parts))
+
+
+def candidates(version: Version) -> list[str]:
+    """Distribution names to try, best guess first.
+
+    Gradle's naming is not consistent across majors: 8.x drops a trailing zero
+    patch (`gradle-8.14-all.zip`; `gradle-8.14.0-all.zip` is a 404) while 9.x
+    keeps it (`gradle-9.0.0-all.zip`; `gradle-9.0-all.zip` is a 404). Getting
+    this wrong swaps the error being fixed for a download failure that does not
+    look like our doing, so order by the observed rule and keep the other form
+    as a fallback.
+    """
+    stripped, full = _stripped(version), _render(version)
+    order = [full, stripped] if version and version[0] >= 9 else [stripped, full]
+    return list(dict.fromkeys(order))
+
+
+def _exists(name: str) -> bool | None:
+    """True/False if the distribution could be checked, None if we could not."""
+    import urllib.error
+    import urllib.request
+
+    url = f"https://services.gradle.org/distributions/gradle-{name}-all.zip"
+    request = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            return response.status == 200
+    except urllib.error.HTTPError as exc:
+        return exc.code == 200
+    except OSError:
+        return None
+
+
+def normalize(version: Version, probe=_exists) -> str:
+    """The distribution name to write into distributionUrl.
+
+    Probes services.gradle.org so a future naming change corrects itself; falls
+    back to the ordering in `candidates` when the network is unavailable, which
+    is no worse than not probing at all.
+    """
+    options = candidates(version)
+    for name in options:
+        if probe(name) is True:
+            return name
+    return options[0]
+
+
+def flutter_minimum_gradle(flutter_root: Path) -> Version | None:
+    """The oldest Gradle this Flutter SDK will apply its plugin against."""
+    checker = flutter_root / _CHECKER
+    try:
+        match = _ERROR_VERSION.search(checker.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+    if not match:
+        return None
+    return tuple(int(group) for group in match.groups())
+
+
+def wrapper_properties(workspace: Path, gradle_root: Path | None = None) -> Path:
+    root = gradle_root or (workspace / "android")
+    return root / "gradle" / "wrapper" / "gradle-wrapper.properties"
+
+
+def read_wrapper_version(properties: Path) -> Version | None:
+    try:
+        match = _DISTRIBUTION.search(properties.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+    return parse_version(match.group(2)) if match else None
+
+
+def set_wrapper_version(properties: Path, version: Version) -> bool:
+    try:
+        text = properties.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    replaced, count = _DISTRIBUTION.subn(
+        lambda m: f"{m.group(1)}{normalize(version)}{m.group(3)}", text
+    )
+    if not count:
+        return False
+    properties.write_text(replaced, encoding="utf-8")
+    return True
+
+
+def ensure_minimum(workspace: Path, flutter_root: Path, gradle_root: Path | None = None) -> str:
+    """Raise the wrapper to Flutter's floor. Returns a line for the build log."""
+    properties = wrapper_properties(workspace, gradle_root)
+    if not properties.is_file():
+        return ""
+    minimum = flutter_minimum_gradle(flutter_root)
+    if minimum is None:
+        return (
+            "::warning::Could not read Flutter's minimum Gradle version from "
+            f"{flutter_root}; leaving the wrapper alone"
+        )
+    current = read_wrapper_version(properties)
+    if current is None:
+        return f"::warning::No Gradle distributionUrl found in {properties}; leaving it alone"
+    if current >= minimum:
+        return f"Gradle wrapper {normalize(current)} meets Flutter's minimum {normalize(minimum)}"
+    if not set_wrapper_version(properties, minimum):
+        return f"::warning::Failed to rewrite the Gradle distributionUrl in {properties}"
+    return (
+        f"::warning::Gradle wrapper {normalize(current)} is below Flutter's minimum "
+        f"{normalize(minimum)}; raised it to {normalize(minimum)} for this build only. "
+        f"Commit the bump in {properties.name} to make it permanent."
+    )

package/android-action/scripts/resolve_android.py

@@ -4,9 +4,11 @@
 from __future__ import annotations
 
 import os
+import shutil
 import sys
 from pathlib import Path
 
+import gradle_wrapper
 from android_config import (
     ConfigError,
     detect_package_name,
@@ -126,6 +128,22 @@ def apply_gradle_version(project, build_number: int, build_name: str) -> None:
         )
 
 
+def flutter_root() -> Path | None:
+    """Where the runner's Flutter SDK lives.
+
+    flutter-action exports FLUTTER_ROOT; a self-hosted runner with Flutter
+    merely on PATH does not, so fall back to walking up from the binary
+    (<root>/bin/flutter).
+    """
+    declared = os.environ.get("FLUTTER_ROOT")
+    if declared:
+        return Path(declared)
+    binary = shutil.which("flutter")
+    if not binary:
+        return None
+    return Path(binary).resolve().parent.parent
+
+
 def main() -> None:
     workspace = Path(os.environ.get("GITHUB_WORKSPACE", ".")).resolve()
     env_path = Path(os.environ["GITHUB_ENV"])
@@ -151,6 +169,18 @@ def main() -> None:
             apply_gradle_version(
                 project, build_number, os.environ.get("INPUT_BUILD_NAME") or ""
             )
+        else:
+            # Flutter refuses to apply its Gradle plugin to a wrapper older than
+            # the SDK's floor, and CI tracks `stable`, so that floor rises
+            # without the app changing. Raise it in the checkout rather than
+            # letting every app in the fleet break on Flutter's release day.
+            root = flutter_root()
+            if root is None:
+                print("::warning::Flutter SDK not found; skipping the Gradle wrapper check")
+            else:
+                message = gradle_wrapper.ensure_minimum(workspace, root)
+                if message:
+                    print(message)
     except (ConfigError, KeyError, OSError) as exc:
         print(f"::error::{exc}")
         raise SystemExit(1) from exc

package/android-action/scripts/test_gradle_wrapper.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Tests for raising a Flutter app's Gradle wrapper to the SDK's floor."""
+
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+import gradle_wrapper as gw
+
+CHECKER_SOURCE = """
+package com.flutter.gradle
+object DependencyVersionChecker {
+    internal val warnGradleVersion: Version = Version(8, 7, 0)
+    internal val errorGradleVersion: Version = Version(8, 14, 0)
+}
+"""
+
+WRAPPER = (
+    "distributionBase=GRADLE_USER_HOME\n"
+    "distributionPath=wrapper/dists\n"
+    "distributionUrl=https\\://services.gradle.org/distributions/gradle-8.11.1-all.zip\n"
+)
+
+
+def never(_name: str) -> bool:
+    """Probe stub for tests: the network is never consulted."""
+    return False
+
+
+class RenderTest(unittest.TestCase):
+    def test_eight_x_drops_a_trailing_zero_patch(self):
+        self.assertEqual(gw.candidates((8, 14, 0))[0], "8.14")
+
+    def test_nine_x_keeps_a_trailing_zero_patch(self):
+        # gradle-9.0-all.zip is a 404; gradle-9.0.0-all.zip is the real name.
+        self.assertEqual(gw.candidates((9, 0, 0))[0], "9.0.0")
+
+    def test_a_real_patch_is_never_stripped(self):
+        self.assertEqual(gw.candidates((8, 14, 3)), ["8.14.3"])
+
+    def test_the_other_spelling_stays_available_as_a_fallback(self):
+        self.assertIn("8.14.0", gw.candidates((8, 14, 0)))
+
+    def test_falls_back_to_the_first_candidate_without_network(self):
+        self.assertEqual(gw.normalize((8, 14, 0), probe=never), "8.14")
+
+    def test_a_successful_probe_wins_over_the_ordering(self):
+        self.assertEqual(
+            gw.normalize((8, 14, 0), probe=lambda name: name == "8.14.0"), "8.14.0"
+        )
+
+
+class WrapperFileTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.workspace = Path(self.tmp.name)
+        self.properties = gw.wrapper_properties(self.workspace)
+        self.properties.parent.mkdir(parents=True)
+        self.properties.write_text(WRAPPER, encoding="utf-8")
+        self.flutter = self.workspace / "flutter"
+        checker = self.flutter / gw._CHECKER
+        checker.parent.mkdir(parents=True)
+        checker.write_text(CHECKER_SOURCE, encoding="utf-8")
+        self.addCleanup(self.tmp.cleanup)
+
+    def test_reads_the_declared_version(self):
+        self.assertEqual(gw.read_wrapper_version(self.properties), (8, 11, 1))
+
+    def test_reads_the_sdk_floor(self):
+        self.assertEqual(gw.flutter_minimum_gradle(self.flutter), (8, 14, 0))
+
+    def test_raises_a_wrapper_below_the_floor(self):
+        gw.set_wrapper_version(self.properties, (8, 14, 0))
+        self.assertEqual(gw.read_wrapper_version(self.properties), (8, 14,))
+        self.assertIn("gradle-8.14-all.zip", self.properties.read_text())
+
+    def test_preserves_a_bin_distribution(self):
+        self.properties.write_text(
+            WRAPPER.replace("-all.zip", "-bin.zip"), encoding="utf-8"
+        )
+        gw.set_wrapper_version(self.properties, (8, 14, 0))
+        self.assertIn("gradle-8.14-bin.zip", self.properties.read_text())
+
+    def test_leaves_a_wrapper_already_at_the_floor_alone(self):
+        self.properties.write_text(
+            WRAPPER.replace("8.11.1", "8.14.3"), encoding="utf-8"
+        )
+        message = gw.ensure_minimum(self.workspace, self.flutter)
+        self.assertIn("meets Flutter's minimum", message)
+        self.assertIn("gradle-8.14.3-all.zip", self.properties.read_text())
+
+    def test_warns_and_raises_when_below_the_floor(self):
+        message = gw.ensure_minimum(self.workspace, self.flutter)
+        self.assertTrue(message.startswith("::warning::"))
+        self.assertIn("8.11.1", message)
+        self.assertIn("gradle-8.14", self.properties.read_text())
+
+    def test_no_wrapper_is_not_an_error(self):
+        self.properties.unlink()
+        self.assertEqual(gw.ensure_minimum(self.workspace, self.flutter), "")
+
+    def test_unreadable_sdk_leaves_the_wrapper_untouched(self):
+        message = gw.ensure_minimum(self.workspace, self.workspace / "nope")
+        self.assertTrue(message.startswith("::warning::"))
+        self.assertIn("gradle-8.11.1-all.zip", self.properties.read_text())
+
+    def test_a_wrapper_without_a_distribution_url_is_left_alone(self):
+        self.properties.write_text("distributionBase=GRADLE_USER_HOME\n", encoding="utf-8")
+        message = gw.ensure_minimum(self.workspace, self.flutter)
+        self.assertIn("No Gradle distributionUrl", message)
+
+    def test_honours_an_explicit_gradle_root(self):
+        root = self.workspace / "nested"
+        properties = gw.wrapper_properties(self.workspace, root)
+        properties.parent.mkdir(parents=True)
+        properties.write_text(WRAPPER, encoding="utf-8")
+        gw.ensure_minimum(self.workspace, self.flutter, gradle_root=root)
+        self.assertIn("gradle-8.14", properties.read_text())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/bin/cli.mjs

@@ -3,13 +3,22 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-import updateNotifier from 'update-notifier';
-
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 
-const notifier = updateNotifier({ pkg });
+// The update nag is a nicety, not a dependency of installing. Running the CLI
+// straight out of a source checkout (`node ../gowalk-cicd/bin/cli.mjs`, the
+// documented local-development path) has no node_modules, and a hard import
+// would take the whole installer down with it.
+async function loadNotifier() {
+  try {
+    const { default: updateNotifier } = await import('update-notifier');
+    return updateNotifier({ pkg });
+  } catch {
+    return { notify() {} };
+  }
+}
 
 const args = process.argv.slice(2);
 let dryRun = false;
@@ -60,4 +69,5 @@ After install:
 const { runInstall } = await import('../src/install.mjs');
 await runInstall({ dryRun });
 
+const notifier = await loadNotifier();
 notifier.notify();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {

package/templates/deploy.yml

@@ -19,8 +19,15 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Repository variable DEPLOY_PLATFORMS selects which stores this repo ships to:
+  #   unset / 'both' — iOS and Android (the default)
+  #   'android'      — Android only; skip the iOS job entirely
+  #   'ios'          — iOS only; skip the Android job entirely
+  # Use it when one platform is intentionally out of scope for a repo, so an
+  # unrelated failure on the other platform cannot block the release you want.
   ios:
     name: iOS TestFlight
+    if: ${{ vars.DEPLOY_PLATFORMS != 'android' }}
     runs-on: macos-15
     timeout-minutes: 60
     steps:
@@ -78,6 +85,7 @@ jobs:
 
   android:
     name: Android Google Play
+    if: ${{ vars.DEPLOY_PLATFORMS != 'ios' }}
     runs-on: ubuntu-24.04
     timeout-minutes: 45
     steps:
@@ -187,6 +195,10 @@ jobs:
           releaseFiles: ${{ steps.android.outputs.bundle-path }}
           tracks: ${{ vars.GOOGLE_PLAY_TRACK || 'internal' }}
           status: ${{ vars.GOOGLE_PLAY_STATUS || 'completed' }}
+          # Play rejects an 'inProgress' release that does not declare how much of
+          # the audience it reaches. Only send the fraction in that mode: passing it
+          # alongside status 'completed' is an error rather than a no-op.
+          userFraction: ${{ vars.GOOGLE_PLAY_STATUS == 'inProgress' && (vars.GOOGLE_PLAY_USER_FRACTION || '0.2') || '' }}
           # Localized release notes: commit distribution/whatsnew/whatsnew-<bcp47>
           # files (e.g. whatsnew-en-US, whatsnew-de-DE) and they ship with every
           # release. Empty when the directory is absent — the action skips it.